How to Use GDB's Source-Tracking Breakpoints to Avoid Manual Resets

Introduction

Imagine you're deep in a debugging session. You've set breakpoints on a handful of lines, inspected variables, and formed a theory about what's wrong. You edit the source code, recompile, and reload the executable—but now your breakpoints point to the wrong lines because the code shifted. Without source-tracking, you'd have to delete each old breakpoint and set new ones manually. That's tedious and interrupts your flow.

How to Use GDB's Source-Tracking Breakpoints to Avoid Manual Resets — Source: fedoramagazine.org

GDB's experimental source-tracking breakpoints solve this problem. When you enable this feature and set a breakpoint using file:line notation, GDB captures a small window of surrounding source code. After you edit, recompile, and reload, GDB automatically adjusts any breakpoints whose line numbers changed. This keeps your debugging session moving without the hassle of resetting breakpoints after every edit-compile cycle.

What You Need

GDB (GNU Project Debugger) version that supports source-tracking breakpoints (experimental feature, typically GDB 12 or later; check your version with gdb --version).
A compiled program with debug symbols (compile with -g flag, e.g., gcc -g -o myprogram myfile.c).
Source code files you will edit during the debugging session.
Basic familiarity with GDB commands (starting GDB, loading executables, setting breakpoints, running).

Step-by-Step Instructions

Step 1: Start GDB and Load Your Program

Launch GDB and load the executable you want to debug. Use the file command or pass the executable as an argument when starting GDB. For example:

gdb ./myprogram

Now you're inside the GDB prompt ((gdb)).

Step 2: Enable Source-Tracking

Before setting breakpoints, turn on the source-tracking feature with the following command:

(gdb) set breakpoint source-tracking enabled on

This tells GDB to capture source context for any breakpoint set from now on. If you want to disable it later, use the same command with off.

Step 3: Set a Breakpoint Using File:Line Notation

Choose a source line where you want to stop execution. Use the break (or b) command with the file name and line number. For example, to set a breakpoint on line 42 of myfile.c:

(gdb) break myfile.c:42

GDB will respond with something like:

Breakpoint 1 at 0x401234: file myfile.c, line 42.

Because source-tracking is enabled, GDB automatically captures a small window (by default, 3 lines around the breakpoint). You can verify this with the info breakpoints command:

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

Note the source-tracking enabled line—it confirms that GDB is tracking this breakpoint.

Step 4: Edit Your Source Code

Now, with GDB still running, edit myfile.c in another window or terminal. Make changes that will shift the line numbers—for example, add a few lines above line 42. Save the file.

Common edits that cause line shifts:

Inserting new code (function calls, variable declarations, comments).
Removing lines above the breakpoint.
Adding or deleting blank lines.

Step 5: Recompile the Program

Exit the editor and recompile your source file. For example:

gcc -g -o myprogram myfile.c

Make sure the new executable overwrites the old one. You can do this while GDB is still running; you don't need to restart GDB.

Step 6: Reload the New Executable in GDB

Back in the GDB prompt, use the run command (or start) to reload the executable:

(gdb) run

GDB will notice that the executable has been changed and will reload it automatically. As part of that reload, it applies the source-tracking algorithm: it attempts to match the captured source lines (the 3-line window) to the new source file. If a match is found, GDB adjusts the breakpoint to the new line number. You'll see a message like:

Breakpoint 1 adjusted from line 42 to line 45.

That means the breakpoint now lives at line 45 because you inserted three lines above it.

Step 7: Verify the New Breakpoint Location

Run info breakpoints again to confirm the update:

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

The address and line number have changed to reflect the new location. You can now continue debugging as usual—the breakpoint will trigger at the intended source line.

Step 8: Continue Debugging (Optional Repetition)

You can repeat steps 4–7 as many times as needed. Each edit-compile-reload cycle will automatically adjust all source-tracked breakpoints. If you add more breakpoints later, they will also be tracked as long as source-tracking remains enabled.

Tips and Limitations

Exact match required. The source-tracking algorithm compares the captured lines literally. Whitespace-only changes (e.g., adding a space or tab) or trivial reformatting of the tracked lines will cause the match to fail. If that happens, GDB will keep the breakpoint at its original location and warn: warning: Breakpoint 1 source code not found after reload, keeping original location. In that case, you'll need to manually reset the breakpoint.
Search window is limited. GDB only looks for the captured lines within a 12-line window around the original location. If your code shift is larger—for example, because you inserted many lines above—the breakpoint won't be found. The same warning as above will appear. Consider keeping edits small or manually adjusting breakpoints after large changes.
Cannot track pending breakpoints. If you use set breakpoint pending on and set a breakpoint on a function or line not yet loaded, GDB cannot capture source context because no symbol table is available. Source-tracking will not work for such breakpoints. Set breakpoints only after the program is loaded, or disable pending mode.
Best practice: Keep tracked lines stable. To maximize success, avoid editing the exact lines captured by the tracking window. Instead, insert new code elsewhere (e.g., above or below them) or add new functions in separate areas. The captured lines should remain as unchanged as possible.
Use with version control. Source-tracking is not a substitute for version control. It's a convenience for ad-hoc debugging. When you're done, consider committing your changes and restarting GDB with fresh breakpoints.
Feature is experimental. As of GDB 14, source-tracking is still marked experimental. It may change in future releases, and edge cases might not work perfectly. Report bugs if you encounter issues.

Source-tracking breakpoints can save you significant time during iterative debugging. By following these steps, you can stay focused on finding bugs rather than managing breakpoints.