Debugging C/C++ Programs Remotely Using Visual Studio Code and gdbserver

If you’re like me and prefer using a GUI to a command line for setting breakpoints, stepping through code, and inspecting values as your program runs, here is how you can set up VSCode and gdbserver to edit and debug your code locally while running it on a remote server.

Background: I’m working on an assignment for CSC469 at the University of Toronto, and it will only compile and run on the university’s teaching lab machines. My goal was to be able to edit and debug locally in a familiar editor while compiling and running on the remote teaching lab machines.

Note: I’m using macOS Sierra locally, with the remote machine running Ubuntu 14.04, but this guide should work with any Unix system. (Sorry, Windows users).

Note: Commands to be run on the remote machine are prefixed with remote$ and local commands are prefixed with local$ .

1. Install gdbserver on the remote machine

Installation varies by system. On Debian/Ubuntu, you can do:

remote$ apt-get install gdbserver

Since students are not allowed to install software via apt on the U of T machines, I used Linuxbrew to install it to my user folder:

remote$ brew install gdbserver

2. Install gdb on your local machine

On macOS Sierra, I used Homebrew to install gdb:

local$ brew install gdb --with-all-targets

Note: The --with-all-targets option is important; without it, you won’t be able to debug on a remote machine with a different OS or architecture than your local machine.

3. Test gdb

At this point, you should be able to run gdbserver on the remote machine and connect to it from your local gdb CLI. I’ll use the -L option of ssh to forward local port 9091 connections to the remote port 9091:

local$ ssh -L9091:localhost:9091 user@remote
remote$ cd ./myproject/ && make
remote$ gdbserver :9091 ./myprogram

(Port 9091 is arbitrary; use any port number you like)

Leave that command running in a terminal window; it will wait until gdb connects before running ./myprogram .

In another terminal window on your local machine, run gdb:

local$ gdb
GNU gdb (GDB) 7.12
Copyright (C) 2016 Free Software Foundation, Inc.
...
For help, type "help".
Type "apropos word" to search for commands related to "word".
(gdb)

Then connect to the gdbserver instance:

(gdb) target remote localhost:9091
Remote debugging using localhost:9091
...
(gdb)

To verify things are working, you can run various gdb commands like info sources , or set a breakpoint with break . Use continue to run ./myprogram .

4. codesign gdb

VSCode prevents you from running gdb unless it’s signed; follow these steps to ensure it’s signed.

5. Synchronize local and remote file systems

You may have noticed that, for basic functionality, the gdb CLI on your local machine doesn’t need to be provided any information about the program or its source code except for the host and port on which gdbserver is running. But there are two big reasons why you’ll want to keep your local and remote project directories in sync:

• Viewing source code in the gdb CLI (i.e. list).
• The VSCode C/C++ extension requires you to provide the path to the compiled executable to launch gdb. (The "program" field in launch.json).

I opted to use sshfs since it required the least server-side setup, but you could use NFS, rsync, or other alternatives.

Using sshfs, mount the remote project folder locally:

local$ mkdir ./myproject
local$ sshfs user@remote:myproject ./myproject

Note: on macOS, you can later unmount the directory with umount ./myproject. On Linux, use fusermount -u ./myproject.

6. Configure Visual Studio Code

Open your newly-mounted project ./myproject/ in VSCode, then open .vscode/launch.json or create it if it doesn’t exist:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "C++ Launch",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceRoot}/myprogram",
      "miDebuggerServerAddress": "localhost:9091",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceRoot}",
      "environment": [],
      "externalConsole": true,
      "linux": {
        "MIMode": "gdb"
      },
      "osx": {
        "MIMode": "gdb"
      },
      "windows": {
        "MIMode": "gdb"
      }
    }
  ]
}

This configuration will make it so clicking “C++ Launch” will run gdb similar to:

local$ gdb ./myprogram
...
(gdb) target remote localhost:9091

7. Write a script to compile your program and launch gdbserver

Ideally, you’d want to be able to run a single command or click a single button to compile & debug your program.

This might be possible to do via VSCode tasks and the preLaunchTask option in launch.json, but I was not able to put together a simple solution using those.

Instead I wrote a quick-and-dirty shell script prepare_remote_debug.sh :

# Kill gdbserver if it's running
ssh user@remote killall gdbserver &> /dev/null
# Compile myprogram and launch gdbserver, listening on port 9091
ssh \
  -L9091:localhost:9091 \
  user@remote \
  "zsh -l -c 'cd myproject && make && gdbserver :9091 ./myprogram'"

8. Start debugging

Here is your new workflow:

1. Edit some code.
2. Run ./prepare_remote_debug.sh in a terminal window. Your program’s output will appear here.
3. Set some breakpoints.
4. Run “C++ Launch”.
5. Step through your code in VSCode’s debugger.
6. Repeat.

That’s it! I hope this helps someone, and let me know if it can be simplified even further.