Debugging Zig with VS Code
Tags: vscode, gdb, zig, lldb
Published: 2020-07-07 22:07:03

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 <kbd>Ctrl</kbd> + <kbd>p</kbd> (<kbd>Cmd</kbd> + <kbd>p</kbd> 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 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> 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:

```json
{
    "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 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> 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:

```json
{
    "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!