diff options
Diffstat (limited to 'docs/config.md')
| -rw-r--r-- | docs/config.md | 91 |
1 files changed, 60 insertions, 31 deletions
diff --git a/docs/config.md b/docs/config.md index 7982ccee..f895e599 100644 --- a/docs/config.md +++ b/docs/config.md @@ -12,9 +12,9 @@ main command file is named `init`: On the two unixes `XDG_CONFIG_HOME` counts only when it is ABSOLUTE, as the XDG base-directory specification requires; an empty or relative value falls -back to the home-directory form (`user_config.xdgBase`, and the test beside +back to the home-directory form (`config.User.path`, and the test beside it). Windows never consults it. An `init` that does not fit the `max_bytes` -read limit — 1 MiB, `src/user_config.zig` — or that cannot be read at all is +read limit — 1 MiB, `config.User` in `src/config.zig` — or that cannot be read at all is treated as no file: `load` takes the `readFileAlloc` error and keeps going. The path still resolves, because "nothing is there yet" is the answer `Config` exists to give. There is one case with no path at all: a native launch with no @@ -29,7 +29,7 @@ and size, tagline scale, panel transition, scene effects, hover delay, platform, native-image support, and (on SDL) whether the executable uses live-built shaders or the paired prebuilt shader snapshot. Platform-dependent rows say `unsupported` instead of looking like an off or -empty supported setting. The four fields of `runtime_config.Capabilities` gate +empty supported setting. The four fields of `config.Runtime.Capabilities` gate them and are stated once as plain data in `builtins.capabilities`: `font_picker` is the SDL GUI and native macOS only, `scene_shaders` the same two, `panel_transitions` every @@ -47,7 +47,7 @@ effective (last spawn)` is the executable the native host really chose after installation lookup and fallback. A changed request remains pending until a terminal is spawned, because the core does not resolve native executables. -The mutable global values live together in the plain `runtime_config.State` record. +The mutable global values live together in the plain `config.Runtime` record. One plain capability record gates the setting registry, leader table, `EffectCode`, and report; the compile-time setting table generates both setter builtins and their `Config` rows. Exhaustive checks require every table-backed @@ -75,12 +75,13 @@ Wrap A line matches a builtin whose name takes NO argument only as that whole word: `Kill` runs, `Kill something` does not. A builtin that takes one (`takes_arg` in `src/builtins.zig`, or a `settings` row whose action is -`shell`, `theme`, `font` or `tagline_size` in `src/runtime_config.zig`) takes +`shell`, `theme`, `font` or `tagline_size` in `config.Runtime.settings`) takes everything after the name as the argument. On a native build that is `Theme`, `ThemeFile`, `Font`, `TaglineSize`, `Shell`, `Save`, `Restore`, `Attach`, -`Find`, `Grep`, `Rename`, `WsSymbols`, `Look`, `Exec`, `Msg` and `EffectCode`. +`Mount`, `Unmount`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`, `Exec`, +`Msg` and `EffectCode`. (`Peek`, `Poke`, `Hexdump` and `Gpio` take one too, but they exist only where -`board_memory.enabled` holds, and that build has no config file.) +`builtins.Board.enabled` holds, and that build has no config file.) `Theme <name>` wants one of the 228 names in the ring. Do not derive the spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the @@ -93,6 +94,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 two lines — build metadata, then the panic message: + +```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 +``` + +NO STACK TRACE, and that is a measured decision rather than an omission. The +frames stay on stderr, where `std.debug.defaultPanic` prints them. Collecting +them here instead HANGS the process: `writeCurrentStackTrace` called from a +panic handler before `defaultPanic` has run wedges at 0% CPU, and +`captureCurrentStackTrace` — which looks like the safe half — takes `SelfInfo`'s +rwlock exclusively on its first call, so a panic inside the walk leaves that +lock held and `defaultPanic` then waits on it forever. What makes `defaultPanic` +survive the same hazard is its own private `panic_stage`, which nothing outside +`std.debug` can reach. A crash that becomes a hang is worse than the crash, so +this file keeps only what it can gather without asking the process any +questions: which build, when, where, and what it said. + +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 @@ -287,18 +326,12 @@ pass is bypassed. CRT works in linear light with restrained scanlines, mask, bloom, curvature, and noise rather than remapping the theme to a strong fixed palette; Ripple and Glitch primarily perturb sample coordinates. -`EffectCode <effect-builtin>` opens the build-embedded effect math, host -paint/submission path, and backend shader/grid sources, for example -`EffectCode PanelAscii` or, in a GUI build, `EffectCode Crt`. TTY exposes it -for its grid transitions; native GUI builds -expose it for transitions and scene shaders. It is absent on web, where no -effect argument could succeed. Shared -passes are shown as shared source segments rather than manufactured per-effect -copies. The command works from an installed binary and does not need the source -checkout beside it. SDL output also labels its shader provenance. An ordinary -build prints the live GLSL that `glslc` compiled for that executable; -`-Dprebuilt-shaders` prints the tracked GLSL snapshot paired with the committed -SPIR-V instead and labels those segments with their `shaders/prebuilt/` paths. +`EffectCode PanelAscii` or `EffectCode Crt` lists the current backend's +build-embedded source paths under `/virtual`. Look opens each full file; +no checkout is needed. TTY exposes grid transitions, native GUI builds also +expose scene shaders, and web has neither. Shared implementations share paths. +SDL reports whether GLSL was compiled during this build or came from the +`-Dprebuilt-shaders` snapshot paired with the committed SPIR-V. `zig build shaders` refreshes both files of every pair together, so editing live GLSL without that explicit refresh changes neither half of a prebuilt executable. @@ -323,15 +356,15 @@ pub const look_preview_delay_frames: ?u16 = null; ## Build-time configuration -Everything above is chosen at runtime or in `src/config.zig`. The build itself -takes these, and this is the whole list — every `b.option` in `build.zig`, -besides `-Dtarget` and `-Doptimize` from `standardTargetOptions` and -`standardOptimizeOption`: +Runtime settings live in `src/config.zig`. Build options are listed below; +`zig build --help` lists the options available for the selected platform, +including the standard `-Dtarget` and `-Doptimize` options. | option | values | default | |---|---|---| | `-Dplatform` | `tty`, `gui`, `web`, `macos`, `esp32p4` | absent builds the tty cli and the SDL gui together | | `-Dstatic` | bool | `false` | +| `-Dquic` | bool; 9P over QUIC using system OpenSSL 3.6+ | `false` | | `-Dmupdf` | bool | on for a native target, off for web and esp32p4 | | `-Djpx` | bool | `true` — JPEG 2000, and with it scanned PDFs | | `-Dtree-sitter` | `disabled`, `zig`, `minimal`, `full` | `full` natively, `zig` for web, `disabled` for esp32p4 | @@ -341,17 +374,13 @@ besides `-Dtarget` and `-Doptimize` from `standardTargetOptions` and | `-Dmacos-identity` | codesigning identity for `pardes.app` | `-` (ad-hoc) | | `-Ddump` | a `dump.zon` to embed in the web shell | none | | `-Dtest-filter` | substring; run only tests whose name contains it | none | +| `-Dtest-rebuild` | bool; force fresh Zig test compilation, retaining cached C dependencies | `false` | +| `-Dhelix-harness` | native reference executable for live differential tests | `HX_HARNESS`, otherwise `hx-harness` on PATH | | `-Desp32p4-cols` | u16, the board's grid width in cells | `56` | | `-Desp32p4-rows` | u16, the board's grid height in cells | `14` | -| `-Desp32p4-cpu-mhz` | u16: `90`, `180` or `360` | `90`, the bootloader default | -| `-Desp32p4-port` | serial port the board is wired to | `/dev/ttyUSB0` | -| `-Desp32p4-prof` | bool; per-phase cycle counts for every frame | `false` | -| `-Desp32p4-firmware` | bool; also build the flashable image and its board steps | `false` | -The five `-Desp32p4-*` options that are not `-Desp32p4-firmware` are registered -unconditionally rather than inside the `-Desp32p4-firmware` block that consumes -them, so `zig build --help` lists them and passing one without the flag is not -an "unknown option" error. +The local board build emits an object. Firmware clock, serial port and profiling +options belong to the sibling `05-zig-p4` toolchain's build. Two build inputs reach the running binary as ordinary values rather than as behaviour. `build.zig` reads `.version` from `build.zig.zon` through an untyped |