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

orion commented

2026-10-23 01:41:59 +00:00

Collaborator

Context

Step 1 of #42 (epic: debug native programs, DEBUGGER.md section 4). The C back end already writes a #line per block, but it ignores the Statement marker a debugged lowering writes (backend/c/body.trb, .Statement(_, _) => {}), and torb build never lowers for debugging. Until that holds, gdb and lldb can only stop block by block.

Source

DEBUGGER.md sections 4, 5 and 18

Goal

torb build --debug produces a native binary that gdb or lldb can break and step in by TorbScript line, statement by statement.

Acceptance criteria

The C back end turns Instruction.Statement(at, ...) into a #line of its location, and nothing else changes for an IR without markers (emit-c.test.trb: the C of a program lowered without debugging is byte for byte what it was; the C of one lowered with it has a #line in front of each statement, and KeepAlive still emits nothing)
torb build --debug lowers with debugging: true and compiles with -O0 -g (/Od /Zi for MSVC) whatever the profile says; without the flag nothing changes. It is listed in torb build --help and docs/tooling/
A fixture program with several statements per block is built with --debug; a script in tools/ (a gate of tier B) checks on linux-x64 that the binary's DWARF line table has an entry for each statement line of the fixture (via the platform's readelf/objdump; the gate skips with a message where neither is installed) and that the binary prints what the plain build prints
The native conformance suite is not run debugged in this step; a decision whether it should be is recorded in the PR once the fixture gate's cost is known
DEBUGGER.md section 4 ("What the later phase adds") and section 18 get a slice row for this step, marked Done

Seed

Adds a driver flag (torb build --debug), so under the contract's definition it touches the seed's surface, but nothing in the compiler's own sources uses the flag and no syntax, native or looked-up std name changes: no seed refresh is needed. If the PR finds otherwise, a refresh stays Torben's.

Size

One PR, two Conventional Commits: feat(backend): a #line per statement of a debugged lowering (emitter + emit-c tests), feat(cli): torb build --debug (flag, gate script, docs).

Dependencies

File overlap with #39 and #403 is small (they edit compiler/src/debugger/, tests/debug/; this step edits backend/c/body.trb, cli/build.trb, tools/). DEBUGGER.md section 18 and 20 overlap with them: rebase after whichever lands first. #403 is already ready and independent.

Part of #42.

## Context Step 1 of #42 (epic: debug native programs, DEBUGGER.md section 4). The C back end already writes a `#line` per block, but it ignores the `Statement` marker a debugged lowering writes (`backend/c/body.trb`, `.Statement(_, _) => {}`), and `torb build` never lowers for debugging. Until that holds, gdb and lldb can only stop block by block. ## Source [DEBUGGER.md sections 4, 5 and 18](https://git.torb.dev/torbscript/language/src/branch/main/docs/design/DEBUGGER.md) ## Goal `torb build --debug` produces a native binary that gdb or lldb can break and step in by TorbScript line, statement by statement. ## Acceptance criteria - [ ] The C back end turns `Instruction.Statement(at, ...)` into a `#line` of its location, and nothing else changes for an IR without markers (`emit-c.test.trb`: the C of a program lowered without `debugging` is byte for byte what it was; the C of one lowered with it has a `#line` in front of each statement, and `KeepAlive` still emits nothing) - [ ] `torb build --debug` lowers with `debugging: true` and compiles with `-O0 -g` (`/Od /Zi` for MSVC) whatever the profile says; without the flag nothing changes. It is listed in `torb build --help` and `docs/tooling/` - [ ] A fixture program with several statements per block is built with `--debug`; a script in `tools/` (a gate of tier B) checks on linux-x64 that the binary's DWARF line table has an entry for each statement line of the fixture (via the platform's `readelf`/`objdump`; the gate skips with a message where neither is installed) and that the binary prints what the plain build prints - [ ] The native conformance suite is not run debugged in this step; a decision whether it should be is recorded in the PR once the fixture gate's cost is known - [ ] DEBUGGER.md section 4 ("What the later phase adds") and section 18 get a slice row for this step, marked Done ## Seed Adds a driver flag (`torb build --debug`), so under the contract's definition it touches the seed's surface, but nothing in the compiler's own sources uses the flag and no syntax, native or looked-up std name changes: no seed refresh is needed. If the PR finds otherwise, a refresh stays Torben's. ## Size One PR, two Conventional Commits: `feat(backend): a #line per statement of a debugged lowering` (emitter + `emit-c` tests), `feat(cli): torb build --debug` (flag, gate script, docs). ## Dependencies File overlap with #39 and #403 is small (they edit `compiler/src/debugger/`, `tests/debug/`; this step edits `backend/c/body.trb`, `cli/build.trb`, `tools/`). DEBUGGER.md section 18 and 20 overlap with them: rebase after whichever lands first. #403 is already ready and independent. Part of #42.

orion added the

loop

ready

labels

2026-10-23 01:42:16 +00:00

orion commented

2026-10-23 01:42:17 +00:00

Author

Collaborator

[loop:torbscript] refine: ready. Step 1 of the epic #42, filed just in time (keyword search of open issues found no duplicate). Goal, testable criteria, design record point (DEBUGGER.md sections 4, 5, 18), seed note and size (one PR, two commits) are in the body. Tokens used for this refine: about 90k.

orion referenced this issue

2026-10-23 01:42:17 +00:00

debugger: debug native programs #42

orion referenced this issue

2026-10-23 01:42:23 +00:00

debugger: debug native programs #42

orion commented

2026-10-23 01:49:37 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261023 until 2026-10-23T07:49:37Z

orion referenced this issue from a commit

2026-10-23 02:08:01 +00:00

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

orion referenced this issue from a pull request that will close it,

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

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

orion commented

2026-10-23 03:17:28 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #408 open (#408), CI green (tier A, tier B incl. the new line-table gate in 4 s, bootstrap, pdisc), next: review. Notes: the C emitter already wrote a #line per statement on main, so commit 1 only pins it with emit-c tests; commit 2 adds torb build --debug, tools/debug-lines.sh, tests/debug-lines/ and the docs. The decision on a debugged native conformance suite (not now, 442 s native run vs 4 s fixture gate) is in the PR body. One CI fix round (pdisc stamp of compiler/CONTRIBUTING.md). Tokens: not metered inside this subagent run.

[loop:torbscript] implement: PR #408 open (https://git.torb.dev/torbscript/language/pulls/408), CI green (tier A, tier B incl. the new line-table gate in 4 s, bootstrap, pdisc), next: review. Notes: the C emitter already wrote a `#line` per statement on main, so commit 1 only pins it with emit-c tests; commit 2 adds `torb build --debug`, `tools/debug-lines.sh`, `tests/debug-lines/` and the docs. The decision on a debugged native conformance suite (not now, 442 s native run vs 4 s fixture gate) is in the PR body. One CI fix round (pdisc stamp of compiler/CONTRIBUTING.md). Tokens: not metered inside this subagent run.

orion referenced this issue from a commit

2026-10-23 03:18:31 +00:00

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