Mastering GDB's Source-Tracking Breakpoints: A Complete Guide

Overview

Breakpoints are the bread and butter of debugging—they let you pause execution at a specific line to inspect variables, check flow, and understand bugs. But when you edit your source code and recompile, line numbers shift, and your carefully set breakpoints become stale. You then have to disable old ones and set new ones manually, disrupting your workflow. GDB's experimental source-tracking breakpoints solve this by remembering the source context around each breakpoint and automatically adjusting its line number after recompilation. This guide walks you through the feature from start to finish, including setup, usage, and common pitfalls.

Prerequisites

Before you begin, make sure you have:

• GDB version 10 or later (the feature is marked experimental). You can check with gdb --version.
• A C or C++ program compiled with debug symbols (-g flag).
• Basic familiarity with GDB commands like break, run, and info breakpoints.
• A text editor to modify your source file between debug sessions.

Enabling and Using Source-Tracking Breakpoints

Enabling the Feature

Source-tracking is not active by default. Turn it on inside GDB with:

(gdb) set breakpoint source-tracking enabled on

This setting persists for the current session. To make it permanent, add it to your .gdbinit file.

Setting a Tracked Breakpoint

Once enabled, any breakpoint you set using the file:line notation will automatically be source-tracked. For example:

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

GDB captures a small window of source code around that line (by default three lines above and below). Breakpoints set with other methods (e.g., function names) are not tracked.

Viewing Breakpoint Status

Use info breakpoints to see which breakpoints are tracked:

(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 extra line confirms that GDB has saved the context.

How GDB Adjusts After Recompilation

Now edit myfile.c—add a few lines before line 42, pushing the original code to line 45. Recompile your program without leaving GDB, and then reload it with run:

(gdb) run
Breakpoint 1 adjusted from line 42 to line 45.

GDB prints a message showing the update. Verify with info breakpoints:

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

The breakpoint now points to the correct new line.

Example Walkthrough

Let's walk through a full scenario. Suppose you have a file calc.c with a function add starting at line 10. You set a tracked breakpoint on line 12:

(gdb) break calc.c:12
Breakpoint 1 at 0x400512: file calc.c, line 12.

You run the program, inspect a and b, and realize you need an extra check. You exit GDB (or keep it open), edit calc.c, and insert two new lines before line 12. The original line 12 becomes line 14. Recompile (gcc -g calc.c -o calc). Back in GDB, run:

(gdb) run
Breakpoint 1 adjusted from line 12 to line 14.

The breakpoint is automatically updated. You continue debugging without missing a beat.

If you want to see the captured source snapshot, use:

(gdb) info breakpoints 1

The output will include the saved lines. This snapshot is what GDB uses to match after recompilation.

Common Mistakes and Troubleshooting

Exact Match Requirement

The source-tracking algorithm compares the captured lines character‑for‑character with the new source file. If you made even a whitespace change inside those lines (e.g., added a space, reformatted the indentation), the match fails and GDB cannot relocate the breakpoint. You'll see:

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

Solution: Avoid cosmetic edits to the lines you are tracking. If you must reformat, consider moving the breakpoint to a different area first.

Window Size Limitation

GDB only searches for a matching pattern within a 12‑line window (6 lines above and 6 below) around the original location. If your code shifts by more than that—for example, because you inserted 20 lines above the breakpoint—the search will fail. The same warning as above appears.

Solution: Be aware of large insertions. If you anticipate a major restructure, you can temporarily disable source-tracking (set breakpoint source-tracking enabled off) and manually reset breakpoints afterward, or set the breakpoint on a function name instead.

Pending Breakpoints

If you use set breakpoint pending on and create a breakpoint for a symbol that isn't yet loaded (e.g., in a shared library), GDB cannot capture the source context because the symbol table is unavailable. The breakpoint will not be tracked and will not adjust after reload.

Solution: Disable pending breakpoints (set breakpoint pending off) or set your breakpoints after the shared library is loaded (e.g., by using a file‑line number that is known to be loaded).

Summary

GDB's source-tracking breakpoints eliminate the tedious cycle of manually resetting breakpoints after each edit‑compile‑debug iteration. By saving a three‑line context around each breakpoint, GDB can automatically relocate it when line numbers shift, provided the changes are relatively small and the tracked lines remain exactly the same. This feature is especially valuable during rapid prototyping or when debugging complex code where line‑level breakpoints are essential.

Keep in mind the limitations: exact text matching, a 12‑line search window, and incompatibility with pending breakpoints. Used wisely, source-tracking can save you significant time and keep you in the flow of debugging.