Debugging Zig with VS Code

I've seen questions regarding this both on Reddit and in the Zig Discord, so I wanted to take a minute to share to all those Ziggites (Ziggies? Ziggos? Zigstronauts?) out there how to easily debug their Zig programs using VS Code and GDB.

First, of course, you will need both VS Code and GDB installed. If you don't... well get them. I'll wait.

Now, with VS Code opened, press Ctrl + p (Cmd + p for those Mac people), paste ext install webfreak.debug into the command input box, and hit enter. This will install the wonderfully built Native Debug extension for VS Code which supports GDB and LLDB. In this walkthrough I'll be giving GDB instructions, but you should be able to make it work with LLDB with very few changes.

Now we need to make a build file. Since Zig is compiled, your program obviously needs to be built before it can be run. Press Ctrl + Shift + p and search for "Tasks: Configure Default Build Task", select it, and follow the prompts until you have a tasks.json file created. You will want to create a "build" task which basically runs zig build with whatever arguments you need. As a point of reference, mine looks like this:

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

all it does is run zig build in the current working directory. My build.zig file does the rest.

Next you will need a launch.json. This can be created by once again pressing Ctrl + Shift + p and searching for "Debug: Open launch.json". When prompted, choose the "C++ (GDB/LLDB)" option. This will generate a launch.json file for you, which will be responsible for telling VS Code how to launch and attach the debugger, in our case GDB.

You'll need to change the program option to the location where your built program will be output, in my case it's "./zig-cache/bin/build", but this will vary.

You'll also need to add preLaunchTask as an option, and set its value to the name of your build command. In the above example the task name is "build". Your final launch.json should look something like this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Launch",
            "type": "cppdbg",
            "request": "launch",
            "program": "./zig-cache/bin/build",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "preLaunchTask": "build",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

And that's really it. Try it out by setting some breakpoints in your code, heading over to the debug tab in the activity bar, and pressing play.

Hope this helped!