Setting up Delve and Air to debug Golang with VS Code

I could not find an in-depth guide on setting up debugging with VS Code.

Decided to go into detail to go through each step understanding the fundamentals of the process like:

Meanings of the options in various commands
How the the tools work

VS Code Extension

Search for Go in VS Code Extensions and install it.

https://marketplace.visualstudio.com/items?itemName=golang.Go

Debugger

You will need to install Delve to get debugging (breakpoints, step through, etc) in VS Code.

go install github.com/go-delve/delve/cmd/dlv@latest

If you used asdf to install Go, delve will be located in:

~/.asdf/shims/dlv

You might want to run asdf reshim after installing a go package.

Live Reloading

Since GoLang is a compiled language, code will be compiled into a single executable. During development, making changes will require us to constantly recompile, which can be a manual process, especially in VS Code.

We will use https://github.com/air-verse/air to do live reloading for us.

It is a command line tool that only needs to be run once within your project folder to watch for changes.

Installation

Install the package. Assuming you have go v1.22 or higher.

go install github.com/air-verse/air@latest

If you used asdf to install Go, air will be located in:

~/.asdf/shims/air

Initialise an air.toml config file in your project root

cd ~/myproject
air init

Edit air.toml's go build command like so:

- cmd = "go build -o ./tmp/main ."
+ cmd = 'CGO_ENABLED=0 go build -gcflags=all="-N -l"-o ./tmp/main .'"'

all: flags should be applied to all packages in build packages
-N: disabled optimisations to ensure generated code closer to source code for easier debugging
-l: disables inlining optimisation where small functions are expanded in place to reduce overhead of function calls, making it easier for debugging
Reasoning from Delve Reference

INFO
air will run with default configurations if:

air.toml file is invalid

You ran the command air without air -c air.toml

It will not use your air.toml file.

Edit air.toml full_bin to run the built binary with [[Delve]].

- full_bin = ""
+ full_bin = "dlv exec ./tmp/main --listen=127.0.0.1:2345 --headless=true --api-version=2 --accept-multiclient --continue --log --"

This will run Delve on port 2345.

Run air in your project folder. You should see the following output.

> cd ~/my-project
> air
  __    _   ___  
 / /\  | | | |_) 
/_/--\ |_| |_| \_ v1.52.3, built with Go go1.22.5

mkdir ~/my-project/tmp
watching .
!exclude tmp
building...
running...
API server listening at: 127.0.0.1:2345
2024-07-28T18:47:07+07:00 info layer=debugger launching process with args: [./tmp/main]
2024-07-28T18:47:09+07:00 debug layer=debugger entryPoint 0x1006e8000 machoOff 0x100000000
2024-07-28T18:47:09+07:00 warning layer=debugger debug_frame workaround not applied: function internal/abi.(*RegArgs).IntRegArgAddr (at 0x1006e9070) covered by 0x1006e9070-0x1006e9110
2024-07-28T18:47:09+07:00 debug layer=debugger Adding target 11503 "/Users/alaay/projects/scheduleasy/tmp/main"
2024-07-28T18:47:09+07:00 debug layer=debugger continuing
2024-07-28T18:47:09+07:00 debug layer=debugger ContinueOnce
2024/07/28 18:47:09 Starting server on :5602

Attaching VS Code to Delve

In your .vscode/launch.config file, add the following:

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Air",
      "type": "go",
      "request": "attach",
      "mode": "remote",
      "port": 2345,
      "host": "127.0.0.1"
    }
  ]
}

In VS Code Run and Debug (CMD + SHIFT + D), start debugging with Attach to Air

[!info] VS Code unable to connect
If VS Code is unable to connect, it is most likely that Delve is not running on port 2345. Try using lsof -i :2345 to check if dlv is running using that port. If it is running, you should see:
$ lsof -i :2345
COMMAND   PID  USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
dlv     15464 username    3u  IPv4 0x201bff14586139e3      0t0  TCP localhost:dbm (LISTEN)

Gotchas

Go is a compiled language. That means that code is compiled into a binary and then executed. Whenever we make changes to the code in vscode:

air will watch for the changes
rebuild the binary
start Delve at 2345

This means that the vscode will be disconnected and you will need to reattach vscode to delve.

Reach out

If anyone has a solution to the gotchas above, please leave a comment! I would really love to find a solution to this.

I come from a Rails background, so I'm super used to being able to just leave the debugger running while I make changes to the code.

References

These great guides helped me out when I first started setting up:

Blog