How GDB Source-Tracking Breakpoints Streamline Debugging Workflows

Introduction

Debugging is an iterative process: you set breakpoints, inspect variables, form hypotheses, edit source code, recompile, and then repeat. In a typical GDB session, changing the source code often shifts breakpoint line numbers, forcing you to manually disable old breakpoints and set new ones—a tedious, error-prone task. The GNU Project Debugger (GDB) now introduces an experimental feature called source-tracking breakpoints that addresses this pain point. This feature automatically adjusts breakpoints to their new locations after source changes, making fast edit-compile-debug cycles smoother.

What Are Source-Tracking Breakpoints?

Source-tracking breakpoints extend GDB’s traditional breakpoint mechanism by remembering a small snippet of the source code surrounding the line where a breakpoint is placed. When you recompile and reload the executable (using the run command), GDB compares the captured source context with the new binary’s debugging information. If the breakpoint’s original line has shifted due to inserted or removed lines, GDB automatically adjusts the breakpoint to the new line number, preserving your debugging setup.

This feature is particularly valuable in ad‑hoc debugging sessions where you frequently edit and recompile without restarting GDB. Instead of manually resetting breakpoints after each change, GDB does the housekeeping for you.

How to Enable and Use Source-Tracking Breakpoints

Enabling the Feature

Source-tracking is not enabled by default. To turn it on, issue the following command in GDB:

(gdb) set breakpoint source-tracking enabled on

Setting a Source-Tracking Breakpoint

Once enabled, set a breakpoint using the standard file:line notation:

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

GDB now captures a window of source lines (by default, 3 lines around the breakpoint). You can verify the tracking status 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)

The output explicitly states that source‑tracking is active.

After Editing and Recompiling

Edit your source file—for example, add two lines above the breakpoint, shifting it from line 42 to line 45. Recompile the program and type run in GDB to reload the new executable. GDB will compare the stored source context with the updated binary. If a match is found, it adjusts the breakpoint automatically:

Breakpoint 1 adjusted from line 42 to line 45.

Running info breakpoints again confirms the new location:

(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 breakpoint now points to the correct line, and you can continue debugging without interruption.

Limitations to Keep in Mind

While source-tracking breakpoints are powerful, they have important constraints:

• Exact string match required: The captured source lines must match the new binary’s source lines exactly. Whitespace-only changes or trivial reformatting (e.g., reindentation, trailing spaces) will cause the match to fail. GDB will leave the breakpoint at its original (now possibly wrong) location and issue a warning.
• Search window limited to 12 lines: GDB only searches for the captured context within a 12‑line window around the original breakpoint location. If the code shifted by more than 12 lines (e.g., because a large block was inserted above), the breakpoint is not found. In that case, GDB keeps the original location and prints a warning like:

warning: Breakpoint 1 source code not found after reload, keeping original location.

• Not available for pending breakpoints: When a breakpoint is created as pending (for example, with set breakpoint pending on because the symbol table is not yet loaded), GDB cannot capture the source context. Therefore, source‑tracking is not supported for pending breakpoints.

Conclusion

GDB’s source-tracking breakpoints bring a welcome improvement to the debugging workflow, especially in rapid edit‑compile‑debug cycles. By automatically adjusting breakpoints after source changes, they reduce manual overhead and help you stay focused on solving the problem. While the feature has limitations—especially around exact matching and the 12‑line search window—it is a valuable experimental addition that streamlines interactive debugging. To get the most out of it, be mindful of the matching rules and consider combining source‑tracking with other GDB features like automatic breakpoint commands.