Debugging Rust with VS Code

(There's a translation to portuguese here)

At the very beginning of my career (2008), I became an Oracle PL/SQL developer. I still don't know exactly why, but we didn't use any debugger back then. To fix the bugs, we would add messages everywhere and try to isolate the problem. The smarter kids would take a "binary search" approach, creating a message every 100 lines, finding out between which lines the problem was (say, between 300 and 400), and then refining the search, placing messages every 10 lines (310, 320 and so on).

When I moved from working with Oracle to work with SAP and its ABAP language (which has a fantastic debugger), I discovered a new world. Then, when the time came for me to change technology again (to Rust) I was suddenly dreaded this question: "will I have a debugger there?"

This is the answer I found.

What you came for: debugging Rust in VSCode

First, you need an extension.

• On Unix (Mac, Linux, ...)? Get CodeLLDB
• On Windows? Get C/C++

Why do you need those?

• Short answer: Rust compiler uses LLVM to interact with the machine, and these extensions allow us to interact with the code that runs at this level (since, you know, Rust is compiled).
• Long answer: Above my paygrade, I'm just the support guy installing things on your computer; instead of asking me, check this.

Now, in your VSCode, follow these steps: Run > Start Debugging > Ok > Yes

The expected result is the creation of the file /.vscode/launch.json that looks something like this:

// File copied from MacOS X
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug unit tests in library 'yourprogram'",
            "cargo": {
                "args": [
                    "test",
                    "--no-run",
                    "--lib",
                    "--package=yourprogram"
                ],
                "filter": {
                    "name": "yourprogram",
                    "kind": "lib"
                }
            },
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

Or this, if you're on Windows:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(Windows) Launch",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/target/debug/yourprogram.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "console": "externalTerminal"
        }
    ]
}

If for some reason I am unaware of, the files were not automatically created, you can copy and paste it (create the .vscode folder at the same level as the src folder).

Besides the example files being from a different OS, in the first one, we have a library crate, while the second one is a binary. If you have both crates in the same project, you will have two or three entries under configurations (depending on whether you have tests or not).

Now, theoretically, you could add a breakpoint to your code (clicking on the left column, creating this red dot).If you can't, it is because this option is deactivated. To solve it, open your Settings and go to Debug (under Features—you can type "breakpoint" in the search bar to find it quickly) and check the "Allow Breakpoints Everywhere" option.

With your breakpoints set up, press F5 or go to Run > Start Debugging (which should work now that you have the file). You should end up with something like this:

Basically, on the left, you have the values loaded on the memory. Things are pretty straightforward while you're handling types like these integers, but can become quite messy when you load things like HashMaps; still, it is far better than nothing.

Didn't work out for you? Comment here, for there is a considerable chance that someone else will have a similar problem.

Debug actions

To wrap it up, these are the actions you may perform while debugging are (from left to right):

• F5 Continue: runs the program until it reaches another breakpoint;
• F10 Step Over: Executes the step without going in; eg. if it is a function, it will not go into it;
• F11 Step Into: Executes the step by going into;
• Shift+F11 Step out: Eg. if you're in a function, it goes back to the caller.
• Shift+Cmd/Ctrl+F5 Restart: Execute from the beginning.
• Shift+F5 Stop: Halt the execution.

That's it. Now you're smarter than the smart kids from my first job :)

Cover photograph by Danilo Batista.