Remote GDB Debugging with C++ — Source Code Strategies

When C++ code is compiled on a dev machine (A) and debugged on a target machine (B), GDB needs to find matching source files. Here are the options, from best to worst.

1. Best: Use gdbserver (no source copy to target)

Run a thin gdbserver on the target; connect full GDB from the dev machine where sources live.

1
2
3
4
5
6
7

# On target machine (machine B):
gdbserver :1234 ./mybinary

# On dev machine (machine A) — where sources & binary live:
gdb ./mybinary
(gdb) target remote target-host:1234
# GDB on machine A has full source access; machine B never needs sources.

Build requirement: the binary on both sides must match exactly (same build artifact).

2. Good: Compile with path remapping, then copy sources anywhere

At compile time on machine A, remap the absolute source paths in the DWARF debug info:

1
2
3
4
5

# GCC / Clang:
g++ -g -fdebug-prefix-map=/home/user/project=/opt/src/project ...

# Or older GCC:
g++ -g -fdebug-prefix-map=/home/user/project=.

Then on the target machine B, copy sources to the remapped path:

1
2

# On dev machine:
rsync -av ./src/ target:/opt/src/project/

GDB on machine B finds them automatically because DWARF now contains /opt/src/project/... instead of /home/user/project/....

3. Flexible: Use set substitute-path in GDB

If you already built without -fdebug-prefix-map, redirect at debug time:

1
2
3
4
5
6

# Copy sources anywhere on target, e.g. /tmp/src/
scp -r ./src/ target:/tmp/src/

# On target in GDB:
(gdb) set substitute-path /home/user/project /tmp/src
(gdb) list   # now shows source lines

Add this to ~/.gdbinit on the target to make it permanent.

4. Quick: Use the directory command

Point GDB to the copied source tree:

1
2
3
4

scp -r ./src/ target:/tmp/src/

# In GDB on target:
(gdb) directory /tmp/src

This adds /tmp/src to the source search path. Simpler than substitute-path but only works if the relative directory structure under the DWARF path matches.

5. Last resort: Copy sources to the exact same absolute path

1
2
3

# If DWARF records /home/user/project/src/main.cpp
# Then on target, put it at exactly the same path:
scp -r ./src/ target:/home/user/project/src/

Fragile — only works when usernames and paths are identical across machines.

Summary

Recommendation: If you control the build, add -fdebug-prefix-map to your CMake/Makefile. If you don’t, use gdbserver — it’s the cleanest workflow and avoids source-sync problems entirely.