Mastering GDB Source-Tracking Breakpoints: A Q&A Guide

Debugging often involves setting breakpoints on specific lines of code, making edits, and recompiling—only to find those breakpoints have shifted out of place. GDB's experimental source-tracking breakpoints aim to solve this by automatically adjusting breakpoint locations after source changes. This Q&A guide covers how to enable, use, and understand the limitations of this feature, helping you streamline your debug cycle.

What exactly are GDB source-tracking breakpoints?

Source-tracking breakpoints are an experimental feature in the GNU Project Debugger (GDB) that remembers a small snippet of the source code around where a breakpoint was set. When you edit the source file, recompile, and reload the executable (using the run command), GDB attempts to locate the same code context by matching the captured lines. If the breakpoint's line number has shifted due to added or removed lines above it, GDB automatically updates the breakpoint to the new correct line. This eliminates the need to manually disable and re-enable breakpoints after each edit-compile cycle, making iterative debugging faster and less error-prone.

How do I enable source-tracking breakpoints in GDB?

To activate this feature, you must explicitly turn it on with the command:

(gdb) set breakpoint source-tracking enabled on

After enabling it, any breakpoint you set using the file:line notation (e.g., break myfile.c:42) will automatically capture the surrounding source lines. Note that the feature is off by default—if you do not issue this command, breakpoints will behave as traditional line-number breakpoints. It is recommended to enable it at the start of your debugging session if you plan to edit and recompile frequently. Once enabled, the info breakpoints command will show a “source-tracking enabled” status for each tracked breakpoint.

How do I set a source-tracking breakpoint?

With the feature enabled, setting a breakpoint is identical to the normal break command. For example:

(gdb) break myfile.c:42

GDB will respond with the usual confirmation, but now it also stores a small context window (by default, three lines around line 42). You can verify the tracking status using info breakpoints:

(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 key is to ensure the breakpoint is set via file:line notation—breakpoints set by function name or address are not source-tracked. Once set, GDB will later attempt to match those captured lines after recompilation.

What happens when I recompile and run again?

After editing the source code (e.g., inserting several lines above the breakpoint), recompile the program and type run in GDB to reload the new binary. GDB will search for the previously captured source lines within a limited window around the original location. If a match is found, the breakpoint is automatically adjusted. For instance, if the breakpoint originally at line 42 now falls on line 45, GDB displays:

Breakpoint 1 adjusted from line 42 to line 45.

You can confirm the update with info breakpoints, which now shows the new line number. This automatic adjustment saves you from manually resetting breakpoints, allowing you to continue debugging without disruption.

How can I verify that a breakpoint is being tracked?

Use the info breakpoints command. Each breakpoint that has source-tracking enabled will display the line “source-tracking enabled” along with the number of lines being tracked (e.g., “tracking 3 lines around line 42”). If you do not see this message, the breakpoint is not source-tracked—likely because the feature was not turned on when the breakpoint was set, or the breakpoint was created using a method other than file:line. It is also advisable to watch for adjustment messages after reloading the executable; if GDB fails to relocate the breakpoint, it will issue a warning instead of adjusting.

What are the limitations of source-tracking breakpoints?

While powerful, the feature has several constraints:

• Exact string match required: The tracking algorithm compares the captured source lines verbatim. Whitespace-only changes or trivial reformatting (e.g., indentation adjustments) will cause the match to fail, and the breakpoint will not be relocated.
• Limited search window: GDB only searches within a 12-line window around the original breakpoint location. If the code shifts by more than 12 lines (e.g., a large function is inserted above), the breakpoint will not be found. GDB will keep the original location and print a warning: warning: Breakpoint 1 source code not found after reload, keeping original location.
• Pending breakpoints excluded: If a breakpoint is created pending (e.g., with set breakpoint pending on), no source context is captured because no symbol table is available at the time of creation.

Can source-tracking work with pending breakpoints?

No, it cannot. When you set a breakpoint that is pending—meaning the symbols for that file or line are not yet loaded (for example, if the library is loaded later or the file is not compiled yet)—GDB cannot capture the surrounding source code because no symbol table exists. The debugger needs access to the source text at the moment the breakpoint is defined. Therefore, you must ensure that the file and line are resolvable when the breakpoint is set. To work around this, load the executable and any shared libraries first, then enable source-tracking and set your breakpoints after those symbols are available.