GDB Source-Tracking Breakpoints: A Smarter Way to Debug Evolving Code

Imagine you're deep in a debugging session, breakpoints carefully placed, and then you make a quick edit to your source, recompile, and reload. With traditional GDB, your breakpoints become stale—pointing to old line numbers. You'd have to disable them and set new ones manually. GDB's new source-tracking breakpoints experimental feature changes that. It automatically adjusts breakpoints when source lines shift after edits, saving you time and frustration. Below, we answer common questions about this feature.

1. What exactly are GDB source-tracking breakpoints and how do they improve my workflow?

Source-tracking breakpoints are an experimental GDB feature that remembers a small window of source code around each breakpoint you set using file:line notation. When you recompile and reload your executable within the same GDB session, the debugger compares the captured code snippet to the new source. If the breakpoint's line has moved due to added or removed lines, GDB automatically relocates the breakpoint to the correct new line. This eliminates the tedious cycle of manually deleting and re-creating breakpoints after every edit-compile run. It's especially handy for ad-hoc debugging where you iteratively tweak code and want to keep your breakpoints aligned without interruption.

2. How do I enable and set a source-tracking breakpoint?

First, turn on the feature with the command: set breakpoint source-tracking enabled on. Then set a breakpoint using file:line syntax, for example: break myfile.c:42. GDB will automatically capture the source lines around line 42 (typically 3 lines by default). You can verify tracking is active by running info breakpoints. The output will show something like: "source-tracking enabled (tracking 3 lines around line 42)". If the feature is off, breakpoints are set normally without any source capture. Remember that source-tracking only works with breakpoints specified by file and line—not with function names or addresses.

3. How does GDB adjust my breakpoints after I edit and recompile?

After you modify your source—say you added two lines above the breakpoint, shifting it from line 42 to line 45—recompile the program and type run to reload. GDB will automatically search for the captured source snippet within a 12-line window around the original location. If a match is found, the breakpoint is relocated to the new line. You'll see a message like: "Breakpoint 1 adjusted from line 42 to line 45." Running info breakpoints again confirms the updated line number. The adjustment happens seamlessly, so you can continue debugging without manual intervention.

4. What are the limitations of source-tracking breakpoints?

The algorithm relies on an exact string match of the captured source lines. Whitespace-only changes or minor reformatting (e.g., adjusting indentation) will cause the match to fail, and GDB will not locate the breakpoint. Additionally, GDB only searches within a 12-line window around the original file line. If your code shift exceeds that—for example, a large block of code is inserted above—the breakpoint won't be found. In such cases, GDB keeps the original location and prints a warning: "warning: Breakpoint 1 source code not found after reload, keeping original location." You will then need to manually adjust or disable that breakpoint.

5. What happens if a breakpoint is created in pending mode?

When you set a breakpoint using set breakpoint pending on, the breakpoint is created without a resolved symbol table or loaded source code. Because no source context exists at that moment, GDB cannot capture the surrounding lines. As a result, source-tracking is not applied to pending breakpoints. The feature only works when the breakpoint is resolved immediately—meaning the file and line are known and the corresponding source is available. If you need source-tracking, avoid using the pending mechanism or delay setting the breakpoint until after the library or object file is loaded.

6. How can I tell if a breakpoint is currently being source-tracked?

The info breakpoints command clearly indicates the tracking status. For each breakpoint, the output will include a line such as "source-tracking enabled (tracking 3 lines around line 42)". If you don't see that text, the breakpoint is either not tracked (because you didn't enable the feature or the breakpoint was set differently) or tracking failed (e.g., due to pending creation). You can also check the show breakpoint source-tracking command to confirm the global setting is on. This transparency helps you quickly understand which breakpoints will automatically adjust after code changes.