Mastering GDB's Source-Tracking Breakpoints: A Step-by-Step Guide

Introduction

Debugging is a constant cycle of setting breakpoints, inspecting values, editing code, and recompiling. Traditionally, after you modify source files, the line numbers shift, and your carefully placed breakpoints become misaligned. You'd then need to disable old breakpoints and set new ones—a tedious, repetitive task. GDB's experimental source-tracking breakpoints change that. When enabled, GDB remembers the source context around each breakpoint and automatically adjusts it to the correct line after recompilation. This guide walks you through enabling, using, and understanding this powerful feature.

What You Need

• GDB version that supports the source-tracking feature (experimental as of GDB 10+).
• A C/C++ project with source files you can edit and recompile.
• Basic familiarity with GDB commands like break, run, and info breakpoints.
• An active GDB session (no need to exit between edits).

Step-by-Step Guide

Step 1: Enable Source‑Tracking

Before setting any breakpoints, turn on the source-tracking feature. In your GDB session, type:

(gdb) set breakpoint source-tracking enabled on

This instructs GDB to capture a small window of source code around each breakpoint you create. You only need to do this once per session.

Step 2: Set a Breakpoint Using file:line

Place a breakpoint the usual way, always using the file:line notation. For example:

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

GDB now stores a snapshot of the source lines surrounding line 42 (by default, three lines above and below). This snapshot is used later to track the breakpoint after code changes.

Step 3: Verify That Tracking Is Active

After setting the breakpoint, confirm that source-tracking is enabled for it by running:

(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)

Look for the line that says source-tracking enabled. If you don't see it, double-check that you enabled the feature in step 1 and that the breakpoint was set using file:line (not just a function name).

Step 4: Edit Your Source Code

Now make changes to the source file where the breakpoint is located. For example, add a few lines above the breakpoint line (line 42). This shifts the breakpoint down—say from line 42 to line 45. You can add comments, new variable declarations, or extra statements. The key is that the original lines around your breakpoint still exist (though at different positions).

Important: The matching algorithm depends on an exact string match of the captured source lines. White‑space changes or trivial reformatting of the tracked lines (e.g., adding an extra space at the start) will confuse the matcher and may cause the breakpoint not to be found.

Step 5: Recompile and Reload the Program

After editing, recompile your project (using make or the appropriate build command). Then, still inside the same GDB session, type:

(gdb) run

GDB automatically detects that the executable has changed and reloads it. While reloading, it attempts to relocate all source‑tracking breakpoints. If the adjustment succeeds, GDB prints a message like:

Breakpoint 1 adjusted from line 42 to line 45.

Step 6: Confirm the New Location

It's always wise to verify that the breakpoint is now where you intended. Run info breakpoints again:

(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)

You'll see that the What column now shows line 45, and the tracking message reflects the new context. Your breakpoint is ready to use in the updated code without any manual intervention.

Tips and Limitations

Source‑tracking is powerful, but it has constraints that you should be aware of to avoid surprises:

• Exact match required: The algorithm compares the stored source lines (exactly three lines by default) with the current source file. Even a single extra space or a comment reformatting in those lines will break the match. To minimize issues, avoid unnecessary edits near your breakpoint.
• Search window is narrow: GDB only searches within a 12‑line window around the original line. If your edits shift the code by more than 12 lines (e.g., inserting a large function above the breakpoint), the breakpoint won't be relocated. Instead, GDB keeps the original location and warns:

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

  To avoid this, consider setting breakpoints on lines that are less likely to move far—such as within functions that are rarely expanded.
• No context for pending breakpoints: If you set a breakpoint with set breakpoint pending on (i.e., the symbol table is not yet loaded), GDB cannot capture source context. The source‑tracking feature is effectively disabled for such breakpoints until they become resolved. It's best to set breakpoints after the symbol table is available (e.g., after the first run or start).
• Works best with small, local edits: The feature shines during ad‑hoc debugging sessions where you make quick changes and recompile. For large refactorings, it's often simpler to reset breakpoints manually.
• Always preview with info breakpoints: After reloading, always run info breakpoints to confirm that every tracked breakpoint adjusted correctly. If you see a warning, you can relocate the breakpoint manually using break again.

By following these six steps and keeping the limitations in mind, you can dramatically speed up your edit‑debug cycle. Say goodbye to the drudgery of deleting and resetting breakpoints after every recompilation!