The trace docs predated the current formatter. Corrected against the real
output (library/modules/trace.sx to_string + examples/expected/1025-errors-
trace-format.stderr):
- error-handling.md: replace the obsolete trace example ("error trace:" /
"raised error.X" / "at func (file:line)") with the real format —
"error return trace (most recent call last):" + per-frame "func at
file:line:col" + source line + caret.
- debugger.md: drop the stale "(planned)" marker on the trace formatter
(it is implemented); the tag-name table note now cites the failable-main
reporter's "unhandled error reached main: error.X" line, not a
nonexistent "raised error.X" trace line.
The interp's .trace_frame op only yields the packed value; the separate
sx_trace_push call op is executed by the interp as a foreign call via
host_ffi/dlsym, so the prior 'no sx_trace_push call runs' / 'never calls
sx_trace_push' phrasing was wrong. The packed low word is the op's
span.start (a source byte offset), not an IR instruction offset; renamed
every ir_offset/offset reference to span.start.
The compiled backend builds each trace Frame global as an LLVM named-struct
constant over the cached getFrameStructType() layout (file, line, col, func,
line_text) via LLVMConstNamedStruct -- a type-safe LLVM struct, not the sx
Frame TypeId / normal struct-emission path. Also correct the file field to
the source basename (full paths live in DWARF).
The .trace_frame op is niladic: it carries no operand and no GlobalId.
The compiled backend yields the interned Frame global's address as the
op's value (reflection.emitTraceFrame); the interpreter yields a packed
(func_id, ir_offset) as the op's value and never calls sx_trace_push
(recovered later by .trace_resolve). The sx_trace_push call is a separate
call op emitted by lower.zig at each push site, consuming the op's value.
Reword every passage that stated the old/wrong model: the niladic
invariant is about the op (not the push site emitting only one
instruction); reflection yields the op's value rather than lowering a
push; the interp returns the packed value rather than calling the foreign
sx_trace_push via host_ffi dlsym.
Name the niladic op `.trace_frame` (no `.trace_frame_push` op exists) in
the trace-path roadmap, matching the rest of the doc and src/ir/inst.zig.
Describe the `.trace_frame` arm as building/interning the Frame global and
yielding its address as the op's value; the separate sx_trace_push call is
emitted by the lowerer via normal call lowering, not by the arm itself.
Refresh the debugging architecture reference for the A7.2 relocation:
DWARF emission lives in src/backend/llvm/debug.zig (DebugInfo) and the
interned Frame / tag-name tables in src/backend/llvm/reflection.zig
(Reflection); emit_llvm.zig is the orchestrator that owns LLVMEmitter and
dispatches to them. Behavior is unchanged; only the file-and-function map,
the 'what's emitted' home, and the debugEnabled() owner are corrected.
Closes out E3's stepping-verification ladder to the extent possible
headlessly.
- Verified `sx build --target ios-sim --emit-obj` produces an
arm64-ios-simulator Mach-O that runs under `simctl spawn` and steps
in lldb (the backtrace shows a dyld_sim frame — the sim runtime).
- Verified the device-applicable .dSYM path: dsymutil collects the
DWARF, and after removing the .o lldb still resolves source via the
.dSYM.
- debug_stepping_smoke.sh gains an optional iOS-sim rung that reuses an
already-booted simulator (never boots one — single-sim policy) and
exercises the .dSYM path; skips cleanly when no sim is booted.
- docs/debugger.md: rungs 1-2 marked verified; the iOS-device rung is
documented as a manual checklist (needs hardware + get-task-allow
signing) — no compiler gap, --emit-obj + standard Apple tools suffice.
E3 is functionally complete and verified across macOS + iOS-simulator.
`sx build --emit-obj` keeps the DWARF-bearing object so a debugger can
step the binary, completing the deep-debug half of the trace story.
- --emit-obj flag + TargetConfig.emit_obj. Implies -O0 (DWARF only
emits at opt none/less); keeps the object at its link-time path
.sx-tmp/main.o so the binary's debug map resolves to it; skips the
Level-1 binary cache; reports the object path. macOS resolves via the
debug map -> .o; Linux carries DWARF in the binary. Build-flow only,
no runtime/codegen change.
- tests/debug_stepping_smoke.sh (3e rung 1; macOS, lldb, not in
run_examples): builds with --emit-obj, drives an lldb file:line
breakpoint, asserts resolution + a source-mapped backtrace. Passing —
proves the slice 1-2 DWARF drives real source-level stepping.
(Also normalizes the 253 .exit trailing newline from the 3c --update.)
Gates: zig build, zig build test, run_examples.sh -> 291 passed.
Each trace frame now shows the offending source line with a `^` caret
under the column — in the catch-handler formatter, the failable-main C
reporter, and the comptime path.
The source line is embedded at compile time as a 5th Frame field
(line_text), not read from disk at runtime: the file field is a
basename and a runtime read would add a filesystem dependency that
fails under the test harness and on locked-down targets.
- errors.lineAt(src, offset): shared helper for the whole source line.
- Frame gains line_text (mirrored in emit_llvm getFrameStructType,
trace.sx Frame, sx_trace.c SxFrame). emitTraceFrame embeds it; the
interp .trace_resolve extracts it from the source map.
- trace.sx (new spaces helper) and the C reporter render the line +
a col-aligned caret, guarded on a non-empty line_text.
Snapshots 243/244/247/253 regenerated. Gates: zig build, zig build
test, run_examples.sh -> 291 passed.
#run failures now print the same `func at file:line:col` trace as
runtime, resolved in-process via the interpreter's IR/source tables.
- Read-side context-split op `.trace_resolve` (mirror of .trace_frame),
lowered from a name-recognized `__trace_resolve_frame(u64) -> Frame`.
- emit_llvm: inttoptr the operand to *Frame + load (the value
.trace_frame stamped in).
- interp: unpack (func_id << 32 | span.start); resolve func/file from
module.functions and line/col via SourceLoc.compute over a new
source_map (setSourceMap wired at every production interp site).
- trace.sx: frame_at -> u64; to_string routes each frame through
__trace_resolve_frame, so one source works in both machines.
Compiled path behavior unchanged (243/244/247 identical; it now loads
via the op). New examples/253-comptime-trace.sx exercises the comptime
path. Gates: zig build, zig build test, run_examples.sh -> 291 passed.
Architecture spec for the debugging subsystem: error return traces
(embedded Frame table, niladic context-split push op, the thread-local
ring buffer), DWARF debug info as a debugger-only artifact, the exact
wiring (file/function map + trace and DWARF data flows), the rationale
for choosing embedded locations over PC+DWARF symbolization, the
runtime-artifacts split, and the macOS -> iOS-sim -> iOS-device stepping
verification ladder.
