How to debug Nim code in VSCode

Below are some steps to help you debug Nim code in Visual Studio Code.

Prerequisites

1. Nim is installed.
2. GDB is installed.
3. VSCode is installed.
4. Python 3 is installed (used for pretty-printing with GDB).
5. The Nim VSCode extension is installed.
6. The Native Debug VSCode extension is installed.
7. This example repository has been cloned with Git.

Steps to setup debugging

This repository contains some files to help setup debugging in VSCode.

1. Open VSCode.
2. File -> Open Folder -> Open the cloned repository folder in VSCode.
3. Open main.nim.
4. Set a breakpoint on line 15 in the file:

5. Build the code (ctrl-shift-b), which should use the build definition in .vscode/tasks.json. My preference is to set "Build on Save" in the VSCode-Nim configuration:

5. Debug -> Start Debugging, which should use the launch config in .vscode/launch.json.
6. Once the breakpoint is hit, let's enable pretty-printing. Otherwise, when you mouse over a symbol in the debugger, you'll see memory addresses instead of values.

Open the Debug Console (at the bottom) and type:

python exec(open("bin/nim-gdb.py").read())

(Note: The version of GDB I have installed was built to run with Python 3, and this script works with Python 3)

After pressing [enter], you should see success:

Note: The nim-gdb.py script was copied from here, and exists in the bin/ directory simply to reduce the number of steps in setting this up. It might be a good idea to update your local copy of this file with the official latest file from the repository.

If running the Python pretty-printing script succeeds, you should be able to mouse over a variable, e.g. a string, and see the value:

You'll notice, however, if you mouseover people[0].name, that it does not show the name of the first person (perhaps the nim-gdb.py script could be modified to support this). Even though this functionality doesn't exist, you can type print people[0].name in the Debug Console to print the value:

Press [enter], and you should see the contents of the variable:

Notes

GDB can be extended with Python, and the nim-gdb.py script can be used from the command-line using this bash script.

The nim-gdb repository seems to be the predecessor to the nim-gdb script in the official Nim repository.

References

Debug Nim with GDB
Nim GDB video
Nim Editor Support
repr method for debugging
Nim VSCode plugin debug feature request
Extending GDB using Python