Mastering GDB Source-Tracking Breakpoints: Your Questions Answered

In this guide, we explore GDB's experimental source-tracking breakpoints, a feature that automatically adjusts breakpoints when your source code changes. Instead of manually updating breakpoints after each edit and recompile, this feature captures a snippet of surrounding code and relocates breakpoints to their intended lines. We answer the most common questions about enabling, using, and troubleshooting this functionality.

What Are Source-Tracking Breakpoints?

Source-tracking breakpoints are an experimental feature in GDB (the GNU Project Debugger) that keeps breakpoints aligned with their original source lines even after you modify and recompile your program. Traditionally, when you edit your source code and rebuild, line numbers shift, causing breakpoints to point to the wrong locations. You then have to disable old breakpoints and set new ones manually. With source-tracking enabled, GDB records a small window of source code around the line where you set a breakpoint using file:line notation. When you reload the executable, GDB searches for that same code snippet in the new binary and automatically adjusts the breakpoint to the new line number. This saves time and reduces frustration during iterative debugging sessions.

How Do I Enable Source-Tracking in GDB?

Enabling source-tracking breakpoints is straightforward. Inside a GDB session, run the command set breakpoint source-tracking enabled on. You can also disable it later with set breakpoint source-tracking enabled off. Note that this feature is currently experimental, so you may want to test it in a controlled environment first. Once enabled, any breakpoint you set using break file:line will automatically be tracked. GDB will capture the surrounding source lines (default: 3 lines around the breakpoint). You can verify tracking status with info breakpoints; it will show “source-tracking enabled” along with the number of tracked lines. This ensures that after recompilation, breakpoints are relocated intelligently.

How Do I Set a Source-Tracking Breakpoint?

After turning on the feature, setting a source-tracking breakpoint is as simple as using the normal break file:line command. For example, break myfile.c:42 creates breakpoint 1. GDB immediately records the surrounding code – typically three lines centered on line 42. The info breakpoints output will indicate that source-tracking is active. If you later edit your source, recompile, and run run (or file to reload the executable), GDB will automatically adjust the breakpoint. It will display a message like “Breakpoint 1 adjusted from line 42 to line 45.” Running info breakpoints again confirms the new line and still shows source-tracking enabled. This process works as long as the code snippet remains recognizable after your edits.

What Happens to Breakpoints After Recompilation?

When you recompile your program and reload it in the same GDB session, the debugger examines all source-tracked breakpoints. For each one, it searches for the previously captured source snippet in the new binary. If a match is found, GDB recalculates the breakpoint line number and updates it. You’ll see a message like “Breakpoint 1 adjusted from line 42 to line 45.” The breakpoint remains enabled and ready to hit. If the snippet is not found (e.g., due to large code shifts or whitespace changes), GDB keeps the original location and prints a warning. It is important to note that the search is limited to a 12-line window around the original line; if the code moved beyond that range, the breakpoint stays put and you may need to set it manually.

What Are the Limitations of Source-Tracking?

Source-tracking has a few important limitations. First, the matching algorithm relies on an exact string match of the captured source lines. Any changes – even whitespace or trivial reformatting – can confuse the matcher and cause the breakpoint not to be found. Second, GDB only searches within a 12-line window around the original line location. If you insert a large block of code above the breakpoint that shifts it by more than 12 lines, the breakpoint will not be relocated. In that case, GDB issues a warning: “warning: Breakpoint 1 source code not found after reload, keeping original location.” Third, source tracking cannot be used when a breakpoint is created as “pending” (e.g., with set breakpoint pending on) because no symbol table is available at that moment. Therefore, always ensure you have loaded the executable before setting tracked breakpoints.

Can I Use Source-Tracking with Existing Breakpoints?

Yes, but only if you enable the feature before setting new breakpoints. Existing breakpoints set before enabling source-tracking will not be automatically tracked. To convert them, you would need to delete and re‑create them after turning on source-tracking. The feature is designed to work with breakpoints defined using file:line syntax; breakpoints set by function name, address, or condition do not benefit from source-tracking. Also, note that if you disable source-tracking, already tracked breakpoints lose their tracking status. GDB will not adjust them on subsequent reloads. It’s best to plan your debug workflow: enable source-tracking at the start, set your breakpoints, make code changes, recompile, and let GDB do the rest.

How to Verify That a Breakpoint Is Tracked?

To confirm that source-tracking is active on a particular breakpoint, use the info breakpoints command. The output will include a column or annotation that says “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, it means either the feature is not enabled globally or the breakpoint was created before you turned it on. You can also check the global setting with show breakpoint source-tracking. After a successful relocation, the breakpoint’s line number updates, but the tracking status remains. If relocation fails, you might still see the original line and a warning. Always rerun info breakpoints after reloading to ensure your breakpoints are in the expected places.