How to Debug Rust with Visual Studio Code

March 24, 2019

Visual Studio Code is my Rust editor of choice. Unfortunately it can't quite debug Rust out of the box.

Configuring the debugger isn't hard. But there are a few steps. I've gone through them several times now. I'm writing this guide to save future me from having to remember them.

Hopefully this guide is useful to a few other folks as well.

Install Rust and VS Code

This should go without saying.

Install Rust
Install Visual Studio Code

Install VS Code Extensions

You'll need to install an extension. Which one depends on your platform.

C/C++ (Windows)
CodeLLDB (OS X / Linux)

It probably makes sense to go ahead and install the Rust extension as well.

Configure VS Code

Now that your tools are installed you need to configure your VS Code launch properties.

Click Debug -> Add Configuration
If you're on Windows then select C++ (Windows)
If you're on Mac or Linux then select LLDB: Custom Launch

This should create and open launch.json. You'll have to manually change the executable name under "program".

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(Windows) Launch",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceRoot}/target/debug/foo.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceRoot}",
            "environment": [],
            "externalConsole": true
        },
        {
            "name": "(OSX) Launch",
            "type": "lldb",
            "request": "launch",
            "program": "${workspaceRoot}/target/debug/foo",
            "args": [],
            "cwd": "${workspaceRoot}",
        }
    ]
}

Text above can be copy-pasta'd.

Next, you should verify breakpoints are enabled. Some readers have reporting needing to this do. Some machines have it enabled by default. 🤷‍♂️

Breakpoint settings

File -> Preferences -> Settings

That's it!

Add a breakpoint. Press F5 to launch. Voila!

Limitations

Debugging Rust works pretty well. It's not perfect. But it's pretty good!

Basic types work fine. Assuming they aren't optimized away by the compiler, of course.

Basic Types

I've found the Rust compiler to be a little more aggressive than C++ when it comes to optimizing away "unused" variables. Sometimes I store intermediate values in variables just for the debugger. Their absence can be mildly annoying.

Vectors work just fine. Thankfully. I wish the unexpanded "preview" was more informative.

Basic Types

Unfortunately other containers don't work at all. HashMap is indecipherable crap. :(

HashMap

Visual Studio 2017 has natvis for C++. It's not great. I have a lot of complaints. It's way better than Rust's nothing.

VisualStudio2017

Mixed Debugging

While working on this post I learned something new. I'm somewhat blown away and want to share it.

I was experimenting with the microprofile library. It wasn't behaving quite like I expected so I stepped into the debugger. Much to my surprise I was able to seamlessly step into the crate's Rust code. But what really shocked me is I could also step right into it's underlying C++ code!

C++ Debugging

All of this "just works". No additional configuration needed. You don't have to manuall specify include paths.

This is awesome! You can easily step-into crate dependencies. If the crate relies on C++ code then you can debug that too.

I had no idea it was this easy. What a delightful surprise!

Example Project

I've put together a small sample project with launch.json pre-configured. This should "just work".

  1. Run cargo build
  2. Open .vscode/ws.code-workspace
  3. Add a breakpoint
  4. Select your debug launch config
  5. Press F5

Download: vscode_rust_example.zip

Final Thoughts

I love debuggers. Using VS Code to debug Rust isn't perfect, but it's pretty good. This guide should have everything you need to get started.

This should work on any platform. However I've only tested Windows and OS X. If I'm missing a step or the process changes please let me know.

Thanks for reading.