[GH-ISSUE #2372] [Design] Free Pascal source debugging with an explicit GDB capability matrix #785

New issue

Open

opened 2026-10-15 18:28:20 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:28:20 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2372

Analyst question

When my Free Pascal executable stops in a procedure, which source line, caller frames and supported local values explain the behavior?

REA currently offers static native analysis and bounded macOS LLDB call observation. #1267 tracks the shared live debugger session. This proposal adds a Pascal-specific conformance lane to that session rather than another generic debugger API.

Proposed outcome

Bind the exact executable, compiler/debug settings, caller-selected DWARF/debug-link files and source roots to retained Evidence. Report stripped, mismatched and optimized-out debug information separately.
Resolve procedure/unit/source-line breakpoints, preserving every ambiguous match, pending resolution and raw emitted symbol name.
Return stopped-frame source locations and typed local observations only when the selected debugger establishes them. Preserve raw values and unavailable facets.
Publish a tested support matrix for strings, records, pointers, arrays, sets, subranges and nested procedures. Do not promise complete Pascal expression support: the current GDB manual documents important limitations.
Inherit stop identities, launch/attach separation, effects, cancellation and cleanup from #1267. Expression evaluation or debugger commands that can run code must remain separately classified.

Acceptance and verification

An owned FPC fixture compiled with a pinned compiler and documented debug flags hits a procedure and line breakpoint through public CLI and MCP.
Duplicate unit/procedure names, a stripped build, an optimized local, separate debug files and an incorrect source mapping have distinct outcomes.
A fixture exercises each advertised Pascal type; unsupported types remain unavailable, with provider/version evidence.
Cancellation while stopped and target exit leave no owned debugger or suspended owned process behind.
One feature specification and one implementation plan live under docs/specs/-pascal-source-debugging/.

Scope decision

This extends runtime debugging. Seek the explicit maintainer decision required by CONTRIBUTING.md before substantial implementation for integration. A proposal or small draft prototype does not establish debugger support. Initial verification should use self-owned programs and caller-installed tools.

Primary references

FPC debugging guide
FPC debug-output options
GDB Pascal limitations
Shared lifecycle: #1267; verification examples: #778.

Originally created by @matbrgz on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2372 [![Type: Architecture / RFC](https://img.shields.io/badge/type-architecture_%2F_RFC-darkred.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Analyst question When my Free Pascal executable stops in a procedure, which source line, caller frames and supported local values explain the behavior? REA currently offers static native analysis and bounded macOS LLDB call observation. #1267 tracks the shared live debugger session. This proposal adds a Pascal-specific conformance lane to that session rather than another generic debugger API. ## Proposed outcome - Bind the exact executable, compiler/debug settings, caller-selected DWARF/debug-link files and source roots to retained Evidence. Report stripped, mismatched and optimized-out debug information separately. - Resolve procedure/unit/source-line breakpoints, preserving every ambiguous match, pending resolution and raw emitted symbol name. - Return stopped-frame source locations and typed local observations only when the selected debugger establishes them. Preserve raw values and unavailable facets. - Publish a tested support matrix for strings, records, pointers, arrays, sets, subranges and nested procedures. Do not promise complete Pascal expression support: the current GDB manual documents important limitations. - Inherit stop identities, launch/attach separation, effects, cancellation and cleanup from #1267. Expression evaluation or debugger commands that can run code must remain separately classified. ## Acceptance and verification - [ ] An owned FPC fixture compiled with a pinned compiler and documented debug flags hits a procedure and line breakpoint through public CLI and MCP. - [ ] Duplicate unit/procedure names, a stripped build, an optimized local, separate debug files and an incorrect source mapping have distinct outcomes. - [ ] A fixture exercises each advertised Pascal type; unsupported types remain unavailable, with provider/version evidence. - [ ] Cancellation while stopped and target exit leave no owned debugger or suspended owned process behind. - [ ] One feature specification and one implementation plan live under docs/specs/<NNN>-pascal-source-debugging/. ## Scope decision This extends runtime debugging. Seek the explicit maintainer decision required by CONTRIBUTING.md before substantial implementation for integration. A proposal or small draft prototype does not establish debugger support. Initial verification should use self-owned programs and caller-installed tools. ## Primary references - [FPC debugging guide](https://www.freepascal.org/docs-html/user/userch10.html) - [FPC debug-output options](https://docs.freepascal.org/docs-html/current/user/usersu15.html) - [GDB Pascal limitations](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Pascal.html) - Shared lifecycle: #1267; verification examples: #778.

bsakaguchi added the

labels

2026-10-15 18:28:20 +00:00

bsakaguchi commented

2026-10-15 18:28:21 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

Design & GDB Compatibility Notes

Objective (ELI5):
Document and test Free Pascal source debugging via GDB MI, maintaining an explicit capability matrix for what GDB can and cannot inspect in FPC binaries.

Capability Matrix Focus:

Document differences between DWARF-2 (-g), DWARF-3 (-gw3), and legacy Stabs (-gl).
Explicitly annotate known GDB limitations with Free Pascal dynamic arrays, sets, and ansistrings as unsupported_type_representation rather than debugger crashes.

@matbrgz commented on GitHub (Oct 12, 2026): ### Design & GDB Compatibility Notes **Objective (ELI5):** Document and test Free Pascal source debugging via GDB MI, maintaining an explicit capability matrix for what GDB can and cannot inspect in FPC binaries. **Capability Matrix Focus:** - Document differences between DWARF-2 (`-g`), DWARF-3 (`-gw3`), and legacy Stabs (`-gl`). - Explicitly annotate known GDB limitations with Free Pascal dynamic arrays, sets, and ansistrings as `unsupported_type_representation` rather than debugger crashes.

bsakaguchi referenced this issue

2026-10-16 21:16:09 +00:00

[PR #785] [CLOSED] fix(deps): remediate reachable archive-parsing advisories #2241

bsakaguchi referenced this issue

2026-10-16 21:16:27 +00:00

[PR #815] [MERGED] fix: integrate 24 reviewed browser/native/semantics corrections #2262

bsakaguchi referenced this issue

2026-10-16 21:16:27 +00:00

[PR #818] [MERGED] fix: address review nits from batch integration follow-ups #2263

bsakaguchi added

enhancement

and removed