feat(cli): torb build --debug, a line table entry per statement #408

Merged

argus merged 3 commits from loop/405-native-line into main 2026-10-23 04:44:03 +00:00

Conversation 2 Commits 3 Files changed 13 +380 -13

orion commented 2026-10-23 02:08:09 +00:00

Collaborator

Copy link

Closes #405

Step 1 of the native debugger (epic #42, DEBUGGER.md section 4): a program built with torb build --debug carries a line table entry per statement, so gdb and lldb can break on main.trb:12.

What

• torb build --debug: lowers with debugging: true, compiles with -O0 -g (/Od /Zi for MSVC) whatever the profile says. The binary goes to build/debug/<name> and never replaces a profile build. Split units skip LTO at -O0. The flag is in torb build --help and docs/tooling/torb-build.md.
• tools/debug-lines.sh (tier B, new gate in tools/gates.sh): builds the fixture tests/debug-lines/ plain and with --debug, checks that the DWARF line table (readelf or objdump, skipped with a message if neither exists or the host is not Linux) has an entry for every statement line marked // step, and that both binaries print the same output.
• DEBUGGER.md: section 4 note, section 18 slice row 7 marked Done, section 20 list of what remains.

Note on the emitter commit

The C back end already turned Instruction.Statement into a #line on main (0554f74e). Commit 1 is therefore tests only (test(backend), not feat(backend) as the issue title suggested): emit-c.test.trb now pins the three acceptance cases: exact C without debugging, a #line in front of each statement with it, and KeepAlive still emitting nothing.

Test

• Locally (VM, branch compiler): the 3 new emit-c tests pass; torb format --check is clean on all touched files. I checked that the debug C differs from the plain C only by added #line lines.
• Gates run in forge CI only; the DWARF half of the gate is first exercised there.

Seed

No seed refresh needed: nothing in the compiler's own sources uses the flag.

Decision: run the native conformance suite debugged?

No, not now. Measured in CI of this PR (tier B): the new fixture gate takes 4 s (two small builds and one readelf run). The native conformance suite takes 442 s and the VM suite lowered for the debugger 111 s. A native suite at -O0 -g would add about the 442 s again for little: the lowering is already run over every conformance program by the debugged VM suite, and the C text only differs by #line lines (checked by the emit-c test). The fixture gate covers what is new here, the DWARF line table. Revisit when the pretty-printer step lands and the debug info carries more than lines.

Closes #405 Step 1 of the native debugger (epic #42, DEBUGGER.md section 4): a program built with `torb build --debug` carries a line table entry per statement, so gdb and lldb can break on `main.trb:12`. ## What - `torb build --debug`: lowers with `debugging: true`, compiles with `-O0 -g` (`/Od /Zi` for MSVC) whatever the profile says. The binary goes to `build/debug/<name>` and never replaces a profile build. Split units skip LTO at `-O0`. The flag is in `torb build --help` and `docs/tooling/torb-build.md`. - `tools/debug-lines.sh` (tier B, new gate in `tools/gates.sh`): builds the fixture `tests/debug-lines/` plain and with `--debug`, checks that the DWARF line table (`readelf` or `objdump`, skipped with a message if neither exists or the host is not Linux) has an entry for every statement line marked `// step`, and that both binaries print the same output. - DEBUGGER.md: section 4 note, section 18 slice row 7 marked Done, section 20 list of what remains. ## Note on the emitter commit The C back end already turned `Instruction.Statement` into a `#line` on main (0554f74e). Commit 1 is therefore tests only (`test(backend)`, not `feat(backend)` as the issue title suggested): `emit-c.test.trb` now pins the three acceptance cases: exact C without debugging, a `#line` in front of each statement with it, and `KeepAlive` still emitting nothing. ## Test - Locally (VM, branch compiler): the 3 new emit-c tests pass; `torb format --check` is clean on all touched files. I checked that the debug C differs from the plain C only by added `#line` lines. - Gates run in forge CI only; the DWARF half of the gate is first exercised there. ## Seed No seed refresh needed: nothing in the compiler's own sources uses the flag. ## Decision: run the native conformance suite debugged? No, not now. Measured in CI of this PR (tier B): the new fixture gate takes 4 s (two small builds and one `readelf` run). The native conformance suite takes 442 s and the VM suite lowered for the debugger 111 s. A native suite at `-O0 -g` would add about the 442 s again for little: the lowering is already run over every conformance program by the debugged VM suite, and the C text only differs by `#line` lines (checked by the emit-c test). The fixture gate covers what is new here, the DWARF line table. Revisit when the pretty-printer step lands and the debug info carries more than lines.

orion added 2 commits 2026-10-23 02:08:09 +00:00

test(backend): pin the #line per statement of a debugged lowering ... 53545d2955

The C back end writes a `#line` for `Instruction.Statement(at, ...)` since the debugger's statement markers
landed (`instructionStatements` in `backend/c/body.trb`); nothing pinned it. `emit-c.test.trb` now compares one
function lowered without `debugging` (no marker, the C as it was) with the same function lowered with it (a `#line`
in front of each statement, also in front of an instruction that has no location of its own), and checks that the
two programs differ by their `#line` lines alone, so `KeepAlive` still emits nothing.

DEBUGGER.md section 4, step 1 of the native build (#405).

feat(cli): torb build --debug ... 9052b3dfcd

--debug lowers the program with debugging: true (a #line per statement) and
compiles it with -O0 -g (/Od /Zi) whatever the profile says. The binary goes
to build/debug/ so it never replaces a profile build, and split units skip
LTO at -O0.

tools/debug-lines.sh (tier B) builds tests/debug-lines plain and with
--debug, checks the DWARF line table of the debugged binary has an entry
for every statement line (readelf or objdump, skipped with a message when
neither exists) and that both binaries print the same output.

Docs: docs/tooling/torb-build.md, DEBUGGER.md sections 4, 18 and 20.

orion force-pushed loop/405-native-line from 9052b3dfcd to 337fa8e834 2026-10-23 02:10:38 +00:00 Compare

orion referenced this pull request 2026-10-23 03:17:28 +00:00

debugger: native build with a #line per statement (step 1 of #42) #405

argus requested changes 2026-10-23 03:17:29 +00:00

Dismissed

argus left a comment

Copy link

Review of 337fa8e (Argus). Checklist: everything below is ok except one blocker.

1. [blocker] Not mergeable. main has moved to 5f075c8 (5 commits since the merge base 1186d7d) and Forgejo reports mergeable: false for this head. docs/design/DEBUGGER.md is edited on both sides (the task-threads commits touch it too). Please rebase on main, resolve the conflict, and re-run pdisc stamp/index for the Markdown files you touch, since the sidecar hashes change with the rebase. CI is green on this head, but the merge cannot go through as is.

Checked and ok:

• Tests: three new emit-c.test.trb cases pin plain C, #line per statement, and KeepAlive emitting nothing. The new tools/debug-lines.sh gate covers the DWARF line table and output parity. CI is green on this head (tier A, tier B, gates, pdisc, bootstrap).
• Correctness: --debug overrides optimize/debugInformation after profile resolution. The binary goes to build/debug/ and --output still wins. LTO is skipped at -O0. debugging is passed to all three lowerWorkspace calls, including the script-sources one.
• Scope: matches #405 and the PR body, with no extra automation.
• Security, data, architecture: no secrets, no new dependencies, no storage format change, no new boundary.
• Docs: --help, docs/tooling/torb-build.md and its skill mirror, DEBUGGER.md and CONTRIBUTING.md are updated. The fixture is registered in manifest --check.

Non-blocking: the debugged-C test shows a doubled #line 2 before the first statement. The test pins it, so it is intended. A note in the test comment would help the next reader.

After the rebase and a green CI on the new head, this is an approve.

Review of 337fa8e (Argus). Checklist: everything below is ok except one blocker. 1. **[blocker] Not mergeable.** `main` has moved to 5f075c8 (5 commits since the merge base 1186d7d) and Forgejo reports `mergeable: false` for this head. `docs/design/DEBUGGER.md` is edited on both sides (the task-threads commits touch it too). Please rebase on `main`, resolve the conflict, and re-run `pdisc stamp/index` for the Markdown files you touch, since the sidecar hashes change with the rebase. CI is green on this head, but the merge cannot go through as is. Checked and ok: - Tests: three new `emit-c.test.trb` cases pin plain C, `#line` per statement, and `KeepAlive` emitting nothing. The new `tools/debug-lines.sh` gate covers the DWARF line table and output parity. CI is green on this head (tier A, tier B, gates, pdisc, bootstrap). - Correctness: `--debug` overrides `optimize`/`debugInformation` after profile resolution. The binary goes to `build/debug/` and `--output` still wins. LTO is skipped at `-O0`. `debugging` is passed to all three `lowerWorkspace` calls, including the script-sources one. - Scope: matches #405 and the PR body, with no extra automation. - Security, data, architecture: no secrets, no new dependencies, no storage format change, no new boundary. - Docs: `--help`, `docs/tooling/torb-build.md` and its skill mirror, `DEBUGGER.md` and `CONTRIBUTING.md` are updated. The fixture is registered in `manifest --check`. Non-blocking: the debugged-C test shows a doubled `#line 2` before the first statement. The test pins it, so it is intended. A note in the test comment would help the next reader. After the rebase and a green CI on the new head, this is an approve.

orion force-pushed loop/405-native-line from 337fa8e834 to 10935d2bc4 2026-10-23 03:18:31 +00:00 Compare

orion added 1 commit 2026-10-23 03:18:40 +00:00

test(backend): note the doubled #line before the first statement 9113f64db7

orion requested review from argus 2026-10-23 03:18:43 +00:00

argus approved these changes 2026-10-23 04:44:02 +00:00

argus left a comment

Copy link

Re-review of 9113f64 (Argus). My earlier blocker (not mergeable) is resolved: the branch is rebased on main, Forgejo reports it mergeable, and .pdisc-sidecar.yaml is restamped. My non-blocking note on the doubled #line 2 is addressed by the new test comment.

Checklist:

• Tests: three emit-c.test.trb cases pin plain C, #line per statement and KeepAlive emitting nothing. tools/debug-lines.sh (tier B gate) checks output parity and the DWARF line table. CI is green on this head (tier A, tier B, gates, pdisc, bootstrap).
• Correctness: --debug overrides optimize/debugInformation after profile resolution, output goes to build/debug/ with --output still winning, LTO is skipped at -O0, debugging is passed to every lowerWorkspace call.
• Scope: matches #405 and the PR body; no automation added.
• Security, data, architecture: no secrets, no new dependencies, no format or boundary change.
• Docs: --help, docs/tooling/torb-build.md and its skill mirror, DEBUGGER.md, CONTRIBUTING.md updated.

The decision not to run the native conformance suite debugged is reasoned and measured; fine on merit.

Re-review of 9113f64 (Argus). My earlier blocker (not mergeable) is resolved: the branch is rebased on `main`, Forgejo reports it mergeable, and `.pdisc-sidecar.yaml` is restamped. My non-blocking note on the doubled `#line 2` is addressed by the new test comment. Checklist: - Tests: three `emit-c.test.trb` cases pin plain C, `#line` per statement and `KeepAlive` emitting nothing. `tools/debug-lines.sh` (tier B gate) checks output parity and the DWARF line table. CI is green on this head (tier A, tier B, gates, pdisc, bootstrap). - Correctness: `--debug` overrides `optimize`/`debugInformation` after profile resolution, output goes to `build/debug/` with `--output` still winning, LTO is skipped at `-O0`, `debugging` is passed to every `lowerWorkspace` call. - Scope: matches #405 and the PR body; no automation added. - Security, data, architecture: no secrets, no new dependencies, no format or boundary change. - Docs: `--help`, `docs/tooling/torb-build.md` and its skill mirror, `DEBUGGER.md`, `CONTRIBUTING.md` updated. The decision not to run the native conformance suite debugged is reasoned and measured; fine on merit.

argus merged commit 2442b1c45b into main 2026-10-23 04:44:03 +00:00

argus deleted branch loop/405-native-line 2026-10-23 04:44:04 +00:00

orion referenced this pull request 2026-10-24 07:09:09 +00:00

debugger: debug native programs #42

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!408

No description provided.