Rust Debugging in Visual Studio Code: Complete Guide

Introduction

Debugging is a crucial phase of software development, and Rust is no exception. Efficient debugging ensures your code runs as expected and helps identify issues early in the development process. In this article, we’ll explore Rust debugging using Visual Studio Code, focusing on how to set up the environment, install the necessary tools, and integrate debugging into your daily workflow. We’ll cover step-by-step configurations for Windows, Linux, and macOS, showing how to run and use the debugger effectively. Finally, we’ll address common issues and offer troubleshooting tips to help you debug Rust code like a pro.

We will follow these steps:

1. Installing the necessary tools
2. Configuring Visual Studio Code for debugging on Windows
3. Configuring Visual Studio Code for debugging on Linux/macOS
4. Running and using the debugger
5. Troubleshooting common issues

1. Installing the Necessary Tools

To debug a Rust project with Visual Studio Code, we need to install some essential tools.

Requirements:

• Rust: If you haven’t installed it yet, follow our dedicated guide on how to install Rust to set it up properly.
• Rust-analyzer: The main extension for Rust in VS Code:
  • Open Visual Studio Code
  • Go to the Extensions section (Ctrl+Shift+X / Cmd+Shift+X on macOS)
  • Search for Rust Analyzer and install it

2. Configuring Visual Studio Code for Debugging on Windows

To debug on Windows, follow these steps:

1. Install the C/C++ extension by Microsoft:
   • Open Visual Studio Code
   • Go to the Extensions section (Ctrl+Shift+X / Cmd+Shift+X on macOS)
   • Search for C/C++ and select the Microsoft extension
   • Click Install

2. Install Microsoft Visual C++ (MSVC) if you haven’t already, via Visual Studio Build Tools, available on Visual Studio.
3. Create a .vscode folder in the root of the project if it doesn’t exist:

   mkdir -p .vscode

4. Inside .vscode, create a launch.json file with the following configuration:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug Rust",
               "type": "cppvsdbg",
               "request": "launch",
               "program": "${workspaceFolder}/target/debug/hello_rust.exe",
               "args": [],
               "cwd": "${workspaceFolder}",
               "preLaunchTask": "cargo build",
               "stopAtEntry": false,
               "externalConsole": false
           }
       ]
   }

• Note: The program field must contain the path to the Rust executable generated after compilation. To ensure it is correct:
  1. Compile the project with cargo build
  2. Check the target/debug/ folder for the generated executable
  3. Update program in launch.json with the correct executable name

3. Configuring Visual Studio Code for Debugging on Linux/macOS

To debug on Linux/macOS, follow these steps:

1. Install the CodeLLDB extension by Vadimcn:
   • Open Visual Studio Code
   • Go to the Extensions section (Ctrl+Shift+X / Cmd+Shift+X on macOS)
   • Search for CodeLLDB and select Vadimcn’s extension
   • Click Install

2. Install LLDB if it is not already present:
   • Linux (Ubuntu/Debian):
     

     sudo apt install lldb

   • macOS:
     

     xcode-select --install

3. Create a .vscode folder in the root of the project if it doesn’t exist:

   mkdir -p .vscode

4. Inside .vscode, create a launch.json file with the following configuration:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug Rust",
               "type": "lldb",
               "request": "launch",
               "program": "${workspaceFolder}/target/debug/hello_rust",
               "args": [],
               "cwd": "${workspaceFolder}",
               "preLaunchTask": "cargo build",
               "stopAtEntry": false
           }
       ]
   }

• Note: Ensure that the program value is correct and points to the Rust executable generated in target/debug/

4. Creating the tasks.json File

To automate the build before debugging, create a .vscode/tasks.json file with the following content:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "cargo build",
            "type": "shell",
            "command": "cargo",
            "args": ["build"],
            "group": { "kind": "build", "isDefault": true }
        }
    ]
}

5. Starting the Debugger

After configuring everything, you can start debugging with these steps:

1. Open the Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D on macOS)
2. Select Debug Rust from the dropdown menu at the top left
3. Press F5 to start the debugger

6. Troubleshooting Common Issues

If you encounter problems, here are some common solutions:

• Debugger does not start? Ensure that the executable path in launch.json is correct.
• Breakpoints ignored? Ensure you have compiled the project in debug mode with cargo build without the --release flag.
• Error ‘Configured debug type cppvsdbg is not supported’? Install the C/C++ extension by Microsoft from the Visual Studio Code Marketplace.
• Error ‘CodeLLDB not found’? Ensure you have installed the CodeLLDB extension on Linux/macOS.

Conclusion

In this article, we have seen how to configure debugging for a Rust project in Visual Studio Code on both Windows and Linux/macOS. Now you can set breakpoints, inspect variables, and control the execution flow to identify and fix bugs effectively.

Additional Resources

• Rust: Installation and Official Guide
• Rust Analyzer on VS Code
• Debugging Rust with Visual Studio Code