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

Introduction

Have you ever been deep in a debugging session with GDB, setting breakpoints on several source lines, inspecting values, and forming hypotheses? You edit your code, recompile, and type run to test the new build—only to find your carefully placed breakpoints have shifted because line numbers changed. Without source-tracking, you must manually disable old breakpoints and set new ones. GDB's experimental source-tracking breakpoints eliminate this hassle. When enabled, GDB captures a snippet of surrounding source code at the breakpoint location. After recompilation and reloading, GDB automatically adjusts breakpoints whose lines moved due to code changes. This guide walks you through enabling and using this feature effectively.

Mastering GDB Source-Tracking Breakpoints: A Step-by-Step Guide — Source: fedoramagazine.org

What You Need

GDB version that supports source-tracking breakpoints (experimental feature introduced in recent releases). Check with gdb --version.
A C/C++ (or other supported language) source file you can edit and recompile.
A compiled executable with debug symbols (-g flag for GCC).
Basic familiarity with GDB commands: break, run, info breakpoints.
A text editor to modify source code between debug sessions.

Step-by-Step Instructions

Step 1: Enable Source-Tracking

Before setting breakpoints, you must activate the source-tracking feature. Inside GDB, run:

(gdb) set breakpoint source-tracking enabled on

This command tells GDB to capture and track source context for all future breakpoints set with file:line notation.

Step 2: Set a Breakpoint Using File:Line

Place a breakpoint with the familiar file:line syntax. For example, if your source is myfile.c and you want to stop at line 42:

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

GDB now stores a small window of lines around line 42. The default window size is 3 lines above and below, but you can adjust it (see Tips).

Step 3: Verify Tracking Is Active

Always confirm that source-tracking is enabled for your breakpoint. Use the info breakpoints command:

(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 “source-tracking enabled” message confirms GDB will adjust this breakpoint after source changes.

Step 4: Edit and Recompile Your Source

Leave GDB running (do not exit). Open your source file in a text editor and make changes above the breakpoint line. For instance, add a few lines of code before line 42. Save the file and recompile your program with debug symbols, e.g.:

gcc -g -o myprogram myfile.c

Keep the same executable name so GDB can reload it.

Step 5: Reload the New Executable

Back in GDB, type run (or r) to restart the program with the new binary. GDB automatically reloads the executable and scans the source code for each tracked breakpoint. If the code has shifted, GDB prints a message like:

Breakpoint 1 adjusted from line 42 to line 45.

Now, when the program hits breakpoint 1, it will stop at the correct new line 45, preserving your debugging session.

Step 6: Confirm the New Location

Run info breakpoints again to see the updated breakpoint details:

(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 line number and address have changed, but the breakpoint remains active and tracked.

Handling Limitations

Source-tracking is powerful but has constraints you should understand:

Exact string matching: The tracking algorithm compares the captured source snippet exactly with the new source. Whitespace-only changes or trivial reformatting of the tracked lines can cause a mismatch. Tip: Avoid reformatting the lines immediately around your breakpoint between compilations.
12-line search window: GDB only searches within a window of 12 lines around the original breakpoint location. If your code shifts by more than that (e.g., a large block inserted above), the breakpoint will not be found. GDB will keep the original location and issue a warning:

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

Pending breakpoints: Breakpoints set with set breakpoint pending on (where no symbol table is yet available) cannot capture source context. Tip: Only use source-tracking breakpoints after the executable is loaded and symbols are resolved.

Tips for Success

Adjust the tracking window size: Use set breakpoint source-tracking lines N before setting breakpoints to control how many lines around your target are captured (minimum 1, maximum 10). A larger window reduces the chance of mismatch from whitespace changes, but increases the risk of collisions if many lines are identical.
Keep GDB running: The feature shines when you stay in the same GDB session. Do not exit GDB after recompilation; just type run to reload.
Test with trivial changes first: Before relying on this feature in complex debugging, practice with small edits to understand the matching behavior.
Disable when not needed: If you prefer manual breakpoint management, turn off source-tracking with set breakpoint source-tracking enabled off to avoid unnecessary overhead.
Use file:line syntax only: Source-tracking works only with breakpoints set by file and line number. Breakpoints set by function name or address are not tracked.

By following these steps and tips, you can streamline your debugging workflow and avoid the frustration of resetting breakpoints after every code change. Source-tracking breakpoints make iterative editing and debugging much smoother.