diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/config.md | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/docs/config.md b/docs/config.md index 7982ccee..b95f207e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -93,6 +93,44 @@ and `ayu_mirage` is helix's `ayu_mirage.toml`. The suffix goes on all of them rather than only the eight that clash today, so a name cannot move when either project gains or loses a file. A name that is not in the ring is ignored. +## Crash records + +A panic appends to `crashes` in that same directory, beside `init`, and only +then prints to stderr (`src/crash.zig`, wired into the panic handlers in +`main.zig` and — because the macOS build roots there — `macos.zig`). stderr is +the one place this program cannot keep a trace: in the TTY shell stderr IS the +screen, so the trace lands on a grid the terminal is being reset out of; the SDL +and AppKit shells have no terminal at all; and a `--detach` session's stderr +goes wherever its launcher left it. The file is appended, never rewritten, and +each record is one line of build metadata, the panic message, and the return +addresses behind it: + +```text +pardes 0.0.2 (a1b2c3d) 2026-09-03T11:20:44Z linux-x86_64 pid 48812 +panic: index out of bounds: index 4, len 4 + 0x11ccb5a + 0x11cc84c + 0x11cc67a +``` + +`addr2line -e <the pardes binary>` turns those into source lines, against the +build the metadata line names. They are addresses rather than the symbolised +trace stderr gets for a measured reason: symbolising from inside a panic +handler, before `std.debug.defaultPanic` has run, HANGS the process — reading +DWARF can itself panic, and the staging that turns a nested panic into +"aborting due to recursive panic" is `defaultPanic`'s own and private. Walking +frames is safe; symbolising them is not. + +Everything about it is best effort and silent: no config directory (a launch +with no `HOME`) means no file, and a directory that cannot be created or opened +leaves the panic exactly as it was before — stderr alone. The directory itself +is created if it does not exist, because the user who never wrote an `init` is +as likely as any other to hit a bug. One record at a time: two threads panicking +at once would otherwise interleave into one buffer, so the second falls straight +through to stderr. Only panics come here; a SIGSEGV is caught one level lower +(`main.zig`'s `debug.handleSegfault`) and unwinding one needs the signal's saved +CPU context. + ## Runtime theme files `ThemeFile <path>` loads one complete theme from a `.zon` file. An absolute |