How to Use GDB's Source-Tracking Breakpoints for Effortless Debugging After Code Edits

Introduction

Imagine you're deep in a debugging session, with several breakpoints strategically placed across your source files. You spot a bug, make a quick edit in your editor, recompile, and reload the binary in GDB—only to find that your carefully set breakpoints now point to the wrong lines, thanks to added or removed code above them. The typical fix is to disable old breakpoints and set new ones manually, breaking your concentration. GDB's experimental source-tracking breakpoints eliminate this friction. When enabled, GDB captures a snapshot of source lines around each breakpoint you set using file:line notation. After you recompile and reload, GDB matches those lines to the new code and automatically adjusts the breakpoint location. This guide walks you through enabling, using, and understanding the limits of this feature, so you can keep your debugging flow intact.

What You Need

• A working installation of GDB (version that supports the experimental source-tracking feature; check with gdb --version; help ensure you have a recent build)
• A C/C++ (or other supported language) project that you can compile and debug
• Basic familiarity with GDB commands: setting breakpoints, running, recompiling
• An editor or IDE to modify source files between debug cycles
• Optional: a Makefile or build script for quick recompilation

Step-by-Step Instructions

Step 1: Enable Source-Tracking Mode

Start GDB with your program (gdb ./myprogram). Before setting any breakpoints, turn on the experimental source-tracking feature:

(gdb) set breakpoint source-tracking enabled on

This instructs GDB to capture source context for every subsequent breakpoint created with the file:line syntax. The setting persists until you disable it with off or exit GDB.

Step 2: Set a Breakpoint Using file:line

Choose a source file and line number you want to stop at. For example, if your file is calc.c and you want to break at line 42:

(gdb) break calc.c:42
Breakpoint 1 at 0x401234: file calc.c, line 42.

GDB now stores a small window of source lines surrounding line 42 (by default, 3 lines).

Step 3: Verify the Breakpoint Is Tracked

Use the info breakpoints command to confirm that source-tracking is active for this breakpoint:

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   0x0000000000401234  in calculate at calc.c:42
        source-tracking enabled (tracking 3 lines around line 42)

The extra line indicates that GDB will attempt to adjust this breakpoint after a recompile.

Step 4: Edit Your Source Code

Open calc.c in your editor and insert a few lines above line 42. For instance, add a new variable declaration or a comment. This shifts the original breakpoint line downward—say from line 42 to line 45. Save the file.

Step 5: Recompile and Reload the Program

Recompile your project (e.g., make or gcc -g -o myprogram calc.c). Back in GDB, issue the run command to reload the new executable:

(gdb) run

GDB automatically scans the tracked source lines and compares them to the current code. If the captured lines match a new location, the breakpoint is moved. You'll see output like:

Breakpoint 1 adjusted from line 42 to line 45.

Step 6: Confirm the New Location

Check info breakpoints again to see the updated line:

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   0x0000000000401256  in calculate at calc.c:45
        source-tracking enabled (tracking 3 lines around line 45)

The breakpoint now points to the correct line. Your debugging session continues without having to manually re‑set anything.

Tips and Best Practices

• Use meaningful file:line breakpoints: This feature works only with file:line syntax, not with function names or addresses. For maximum benefit, adopt the habit of setting breakpoints by file and line.
• Keep tracked lines stable: The matching algorithm relies on an exact string match of the captured source lines. Avoid whitespace-only changes or trivial reformatting (e.g., adjusting indentation) in the range of tracked lines, as this will confuse the matcher and may cause the breakpoint to remain at the original location.
• Mind the search window: GDB only looks within a 12‑line window around the original breakpoint location. If big blocks of code are inserted above, shifting the line by more than 12 positions, the breakpoint won't be found. In that case, GDB keeps the original location and prints a warning: warning: Breakpoint 1 source code not found after reload, keeping original location. Consider breaking large insertions into smaller edits, or set the breakpoint again manually if needed.
• Avoid pending breakpoints: Source context cannot be captured when a breakpoint is created in pending state (e.g., with set breakpoint pending on), because no symbol table is available. Always ensure the module is loaded before setting tracked breakpoints.
• Experimental nature: This feature is marked experimental. It may change in future GDB releases. Use it with the understanding that it's still under development. Test it in a non‑critical session first.
• Combine with watchpoints: For data breakpoints (watchpoints), similar source‑tracking is not yet available. You can still manually adjust them after edits.
• Script for efficiency: If you have many breakpoints, consider writing a GDB script that enables source‑tracking at startup, then sets breakpoints. This saves typing in every session.