7 Must-Know Facts About GDB Source-Tracking Breakpoints

Debugging often feels like a game of whack-a-mole—you set breakpoints, edit code, recompile, and then scramble to reset those breakpoints because line numbers have shifted. GDB's new source-tracking breakpoints, an experimental feature, change that by automatically adjusting breakpoints after source changes. This article unpacks everything you need to know: what they are, how to use them, their clever tracking mechanism, and the current limitations. Let’s dive in with seven key points that will save you time and frustration.

1. What Are Source-Tracking Breakpoints?

Source-tracking breakpoints are a new GDB feature that remembers the source line where you set a breakpoint, not just the line number. When you edit your code and recompile, GDB automatically relocates the breakpoint to the new line position—no more manual disabling and re-enabling. This is perfect for iterative debugging cycles: you edit, compile, and continue debugging without breaking flow. The feature is experimental, meaning it may have rough edges, but it already makes ad-hoc debugging sessions far more productive.

2. Enabling the Feature

Before you can use source-tracking, you need to turn it on with a single command. In GDB, run:

set breakpoint source-tracking enabled on

This activates the tracking mechanism for all subsequent breakpoints set via file:line notation. The setting persists for the session, so you only need to do it once. If you ever want to disable it, use set breakpoint source-tracking enabled off. See How to Set a Tracked Breakpoint for the next step.

3. Setting a Source-Tracked Breakpoint

Once the feature is enabled, set a breakpoint using the normal file:line syntax. For example:

break myfile.c:42

GDB will respond with something like:

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

Behind the scenes, GDB captures a small window of the source code around line 42 (the exact size is configurable). This snapshot is used later to match the line even after edits. The breakpoint now becomes “tracked.” You can verify this with info breakpoints, as shown in Item 5.

4. How GDB Tracks and Adjusts Breakpoints

The core of the feature is simple: when you set a breakpoint with file:line, GDB records the surrounding source lines (by default, 3 lines around the target). Later, after you recompile and run the binary again, GDB finds the new binary’s source lines and searches for a match. If the captured snippet appears in the new source (taking shifts into account), GDB automatically updates the breakpoint to the new line number. It even prints a message like:

Breakpoint 1 adjusted from line 42 to line 45.

This works because GDB uses the snippet as a fingerprint—no external database or complex diff required.

5. Verifying Tracking with 'info breakpoints'

To confirm that a breakpoint is being tracked, use the info breakpoints command. You’ll see an extra annotation:

source-tracking enabled (tracking 3 lines around line 42)

After a reload and adjustment, the display updates—for example:

source-tracking enabled (tracking 3 lines around line 45)

This transparency lets you monitor which breakpoints are dynamic and which are static. If a breakpoint fails to adjust, the output will show a warning (see Item 7).

6. Limitation: Exact String Match Required

Source-tracking relies on an exact string match of the captured lines. That means even minor whitespace changes—like extra spaces or tab adjustments—can break the matching algorithm. Similarly, code reformatting (e.g., renaming a variable or rewriting a comment) will prevent GDB from finding the original snippet. So while the feature is powerful, it works best when you only add or remove lines around the breakpoint, rather than altering the captured lines themselves. If the match fails, GDB keeps the breakpoint at its original location and issues a warning (see next item).

7. Limitation: Window Size and Pending Breakpoints

GDB only searches within a 12-line window centered on the original location. If your edits shift the breakpoint by more than 12 lines (say, you inserted a large function above), the snippet won’t be found. In that case, GDB displays a warning and retains the breakpoint at the old line number, which may point to completely different code. Additionally, source-tracking does not work for pending breakpoints—those created with set breakpoint pending on when the symbol table isn’t yet loaded. For pending breakpoints, no source context can be captured, so they remain static.

Source-tracking breakpoints are a game-changer for fluid debugging, but they come with caveats. As an experimental feature, expect refinements in future GDB releases. For now, use them in scenarios where edits are small and line shifts are moderate. Enable the feature, set your breakpoints, and let GDB do the heavy lifting—freeing you to focus on what matters: fixing the bug.