Re: [PATCH v9] gdb: Add source-tracking breakpoints feature

[Eli Zaretskii <eliz@gnu.org>]

> From: Alexandra Hájková <ahajkova@redhat.com>
> Cc: ahajkova@redhat.com
> Date: Fri,  7 Aug 2026 12:46:37 +0200
> 
> When we rerun the executable after changing its source files,
> GDB would re-set all previously set breakpoints. The
> breakpoints set to the function names would remain at their initial
> locations. But the breakpoints which used filename:line notation would
> be silently shifted following the source code changes.
> 
> To address this, GDB now optionally captures a small window of source
> code lines around each breakpoint set with filename:line notation,
> when it is first set. When the binary is reloaded, GDB detects the BFD
> change and tries to locate the same source context in the new file,
> and if successful, re-sets the breakpoint to the matched source code
> line.
> 
> The breakpoint_source structure stores captured source code lines
> around a breakpoint location, along with a reference to the BFD
> that was current when the source was captured.
> 
> When source tracking is enabled (via 'set breakpoint source-tracking
> enabled on'), GDB captures 3 lines of source context
> (BREAKPOINT_SRC_CTX_LINES) along with the current BFD when a
> breakpoint is first set.  On executable reload (detected by comparing
> BFDs), it searches within a 12-line window
> (BREAKPOINT_SRC_CTX_LINES * BREAKPOINT_SRC_SEARCH_MULTIPLIER) for
> the best match and adjusts the breakpoint location if needed.
> 
> If source tracking is disabled after breakpoints have been tracked,
> all existing source tracking information is discarded and a message
> is printed.
> 
> Tests added:
>   gdb.base/adjust_breakpoint.exp
>   gdb.base/adjust_breakpoint-missing-source.exp
>   gdb.base/source-tracking-inline.exp
>   gdb.base/test_source_tracking.exp
> 
> adjust_breakpoint.exp covers four scenarios:
>   - adjust the breakpoint when lines are deleted
>   - adjust the breakpoint when lines are inserted
>   - the tracked line disappears entirely
>   - verify the tracking can be disabled
> 
> adjust_breakpoint-missing-source.exp covers the edge case where source
> files are unavailable, verifying GDB falls back to non-tracking breakpoints.
> 
> source-tracking-inline.exp covers source tracking with inline functions.
> 
> test_source_tracking.exp verifies that source context is correctly captured
> when the breakpoint is on the last line of the file.
> 
> Add maintenance command to print tracked source code.
> Add documentation for the new source-tracking breakpoints feature.
> 
> Limitations of the current implementation:
> 
> Source tracking is not enabled for pending breakpoints that become
> non-pending.  When a breakpoint is created pending (e.g. with 'set
> breakpoint pending on'), source context is not captured at creation
> time since no symtab is available yet.  When the breakpoint later
> resolves to a location, re_set_default() only updates existing tracked
> breakpoints and does not initiate tracking for newly resolved ones.
> This could be fixed in the future by initiating source tracking in
> re_set_default() when a breakpoint transitions from pending to
> non-pending.
> 
> Source tracking for ranged breakpoints is not currently supported.
> Ranged breakpoints have a start and end location spec, and tracking
> both independently raises questions about whether to preserve the
> range length or track each end separately.  For now, ranged
> breakpoints will never be source-tracked.
> 
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
> ---
> 
> v9:
> - Add test_source_tracking.exp description to commit message.
> - Use plongest instead of pulongest for signed line_num.
> - Use error() instead of gdb_printf for non-tracked breakpoints in
>   maintenance_info_source_tracking_context, matching documentation.
> - Discard empty breakpoint_source with bp_source.reset() when
>   source capture fails.
> - Replace non-ASCII em-dashes with ASCII dashes in comments.
> - Move trailing comment before set_string("") to its own line.
> - Fix tab indentation on warning continuation line.
> - Remove trailing blank lines from test files.
> - Add maintenance info source-tracking-context to NEWS.
> - Generalize sliding_window_match to compare all captured context
>   lines instead of only the immediate neighbors, so the matching
>   scales with BREAKPOINT_SRC_CTX_LINES.
> - Use a best-match scoring approach: for each candidate where the
>   breakpoint line matches, count how many context lines also match
>   and select the highest-scoring position.
> - Require a majority of context lines to match before accepting,
>   reducing false positives on common lines like "return 0;".
> - Update function comment and texinfo documentation to describe
>   the new algorithm.
> 
>  gdb/NEWS                                      |  17 +
>  gdb/breakpoint.c                              | 486 ++++++++++++++++++
>  gdb/breakpoint.h                              |  15 +
>  gdb/doc/gdb.texinfo                           |  44 ++
>  .../gdb.base/adjust_breakpoint-2.cpp          |  39 ++
>  .../gdb.base/adjust_breakpoint-3.cpp          |  41 ++
>  .../gdb.base/adjust_breakpoint-4.cpp          |  37 ++
>  .../adjust_breakpoint-missing-source.exp      |  55 ++
>  gdb/testsuite/gdb.base/adjust_breakpoint.cpp  |  40 ++
>  gdb/testsuite/gdb.base/adjust_breakpoint.exp  | 167 ++++++
>  .../gdb.base/source-tracking-inline-1.c       |  50 ++
>  .../gdb.base/source-tracking-inline-2.c       |  49 ++
>  .../gdb.base/source-tracking-inline.exp       |  80 +++
>  gdb/testsuite/gdb.base/test_source_tracking.c |  18 +
>  .../gdb.base/test_source_tracking.exp         |  42 ++
>  15 files changed, 1180 insertions(+)
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint-2.cpp
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint-3.cpp
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint-4.cpp
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint-missing-source.exp
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint.cpp
>  create mode 100644 gdb/testsuite/gdb.base/adjust_breakpoint.exp
>  create mode 100644 gdb/testsuite/gdb.base/source-tracking-inline-1.c
>  create mode 100644 gdb/testsuite/gdb.base/source-tracking-inline-2.c
>  create mode 100644 gdb/testsuite/gdb.base/source-tracking-inline.exp
>  create mode 100644 gdb/testsuite/gdb.base/test_source_tracking.c
>  create mode 100644 gdb/testsuite/gdb.base/test_source_tracking.exp

Thanks, the documentation parts are okay.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>