How to set up GDB for debugging Rust programs in Windows?

Question

How can I configure GDB for debugging Rust programs in Windows, including setting-up the Rust pretty-printers, and debugging either in an IDE or the command-line?

Answer 1

Rust installation

First, you need to compile your programs with the Windows GNU ABI Rust installation. The MSVC ABI uses a different debugging format than the one GDB understands, so that won't work. MSVC ABI compiled programs would have to debugged with Visual Studio (or possibly LLDB, in the future).

GDB

Second step is to get GDB itself. The recommended option is to get it from either TDM-GCC or mingw-w64:

• TDM-GCC (http://tdm-gcc.tdragon.net/): Has available a download package with GDB only (without GCC or the other tools, which you don't need). Special keys work in Windows terminal only. Recommended GDB for use with Eclipse/RustDT.
• Mingw-w64 (http://mingw-w64.org/): Special keys work in Windows terminal only. Recent versions seems to have a bug: command-line arguments with spaces in them are parsed incorrectly.
• Cygwin: Not recommended. Special keys work in Windows terminal and bash terminal. Paths have to be specified in Cygwin format, and this seems to break a few things. Doesn't work properly with Eclipse/RustDT.

Enabling pretty-printers

Rust provides some extensions to GDB to enable a better display of certain Rust native types, such as enums, slices, and vectors. With the pretty-printers, variables of this type will be displayed in a structured way, instead of the low-level representation. For more info see https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html .

The pretty-printers are only included in the Linux (and Mac OS?) distributions of Rust, not the Windows one (Issue reported). But they can be made to work in Windows.

Download the Linux Rust archive (https://www.rust-lang.org/downloads.html), extract and locate the rustc/lib/rustlib/etc directory inside. Now copy the etc folder to $RUST/bin/rustlib , where $RUST is the location of your Rust installation. The Python scripts there will then be located in $RUST/bin/rustlib/etc.

If you only intend to use GDB from within RustDT, and have RustDT 0.4.1 or above, you can skip to the next section: "Using GDB in Eclipse with RustDT".

Now, GDB needs to be configured to load these scripts. Locate the gdbinit file of your GDB installation (for TDM-GCC, should be gdb64\bin\gdbinit, for mingw-w64: mingw64\etc\gdbinit). Now add the following text to the end of the file:

python
print "---- Loading Rust pretty-printers ----"

sys.path.insert(0, "$RUST_GDB_ETC")
import gdb_rust_pretty_printing
gdb_rust_pretty_printing.register_printers(gdb)

end

But replace $RUST_GDB_ETC with the location of the etc directory with the Python files, for example D:/devel/tools.Rust/rust/bin/rustlib/etc. Note, even though it's a Windows path, make sure you use the forward-slash ('/') as a path separator, to avoid escape issues in that string literal.

To verify this works, start gdb. If you see the "---- Loading Rust pretty-printers ----" message before the prompt and no Python errors after, things should be working. To confirm, type the command info pretty-printer. There should be a line with "rust_pretty_printer_lookup_function" in the output if the pretty-printers were loaded successfully.

Using GDB in Eclipse with RustDT

If you successfully completed the steps before, you are nearly good to go to use GDB from within RustDT. Just a few details:

• If using TDM GDB, the GDB executable to be started must be the one at $TDM_ROOT/gdb64/bin/gdb.exe, not the ones at $TDM_ROOT/bin/gdb.exe or $TDM_ROOT/bin/gdb64.exe, because these last two are wrappers for the correct executable, and they don't work properly when RustDT/CDT starts the GDB process.

• If using RustDT 0.4.1 or above, the pretty-printers will be configured automatically, as long as RustDT finds them in ${RUST_ROOT}/lib/rustlib/etc. You can verify this worked by starting a debug launch, opening the corresponding "gdb traces" console page in the Console view, and searching for the string "Registering Rust pretty-printers for Windows":

• For RustDT versions prior to 0.4.1, to enable the pretty-printers, you much configure the launch configuration to run the gdbinit file that you just modified in the previous section. The default gdbinit is not executed when GDB is started by RustDT/CDT, only the one you specify in the configuration. So change the "GDB command file" field from .gdbinit to, for example D:\devel\tools\TDM-GDB\gdb64\bin\gdbinit: