diff options
Diffstat (limited to 'docs/config.md')
| -rw-r--r-- | docs/config.md | 53 |
1 files changed, 22 insertions, 31 deletions
diff --git a/docs/config.md b/docs/config.md index 448ac763..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 @@ -325,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. @@ -361,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 | @@ -379,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 |