summaryrefslogtreecommitdiff
path: root/docs/typ/building.typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ/building.typ')
-rw-r--r--docs/typ/building.typ79
1 files changed, 55 insertions, 24 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index d551c251..d8c089f6 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -1,6 +1,6 @@
// Building pardes, for contributors: platforms, options, tests, the
// release gates and sending patches, then how the pieces fit: the core
-// and its shells, the threads, detached sessions, the 9P engine, the
+// and its shells, the threads, the daemon and its sessions, the 9P engine, the
// listeners and mounts.
#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
@@ -19,7 +19,7 @@ builds MuPDF and is on by default (`-Dmupdf=false` drops it). 9P over QUIC
[`zig build`], [the terminal shell and the SDL window together, *installed into `~/.local/bin`* (`pardes`, `pardes-gui`, and `pardes-v9fs`, the #word("Tty9p") helper)],
[`zig build -Dplatform=tty`], [the terminal shell alone],
[`zig build -Dplatform=gui`], [the SDL3 window alone],
- [`zig build web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<dump.zon>`], [a freestanding wasm core plus vanilla JavaScript (`docs/web.md`)],
+ [`zig build web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<file>`], [a freestanding wasm core plus vanilla JavaScript (`docs/web.md`)],
[`zig build -Dplatform=macos`], [an AppKit and CoreText app over a static `libpardes.a` (`docs/macos.md`)],
[`zig build -Dplatform=esp32p4`], [a freestanding riscv32 editor object for the ESP32-P4, with a 384 KiB heap],
)
@@ -31,7 +31,8 @@ leaves that copy out. Zig 0.17 keeps the prefix from the build script, so
so always pass `-Dplatform` while developing. Test, benchmark and run steps build what they need
without installing. `pardes --version` prints `pardes <version>` (from
`build.zig.zon`), plus the commit for release builds and the `~/.local`
-install; `pardes --help` lists every flag.
+install, and on a second line the build's semantics hash, which a replica
+must share with its session; `pardes --help` lists every flag.
The ESP32-P4 firmware is linked in the sibling `../05-zig-p4` toolchain,
which needs ESP-IDF register headers: after building the editor object
@@ -58,7 +59,7 @@ there; its namespace is in `src/esp32p4_gpio.zig`.
[`-Dprebuilt-shaders`], [bool: embed the committed SPIR-V; on for a bare `zig build`, off with `-Dplatform`; `zig build shaders` refreshes it with glslc],
[`-Dtracy`], [path to a Tracy checkout; off],
[`-Dmacos-identity`], [codesigning identity for `pardes.app`; `-` (ad hoc)],
- [`-Ddump`], [a `dump.zon` to embed in the web shell],
+ [`-Ddump`], [a Dump to embed in the web shell],
[`-Dtest-filter`], [run only tests whose name contains it; a filter that matches nothing fails],
[`-Dtest-rebuild`], [bool: fresh Zig test compilation],
[`-Dhelix-harness`], [reference executable for live differential tests; `HX_HARNESS`, else `hx-harness` on `PATH`],
@@ -177,8 +178,9 @@ Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`,
`src/Terminal.zig`, ...), `src/layout.zig`, `src/fs.zig` (host access,
mounts and resolution) and `src/pardes.zig` (input), with one file per
thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`,
-`mouse.zig`, ...). `src/ninep/` is the control tree, `src/detached/` the
-wire, the detached core and the frontend client, `src/lsp/` the
+`mouse.zig`, ...). `src/ninep/` is the control tree, `src/daemon.zig` the
+per-user daemon and a terminal's stub, `src/detached/wire.zig` the input
+wire a remote client will speak, `src/lsp/` the
language-server client; `test/` holds harnesses, goldens and helix cases,
`build/` the snapshot suite's build step.
@@ -197,26 +199,55 @@ reading the live core, and a request id, the pane's serial and (for an
edit) the file's revision reject a stale reply. A process that never calls
`turn.start` (the tests, the ESP32-P4, the browser) has no second thread.
-== Detached sessions
+== The daemon and detached sessions
-One poll loop in `src/detached/server.zig` owns core mutation, frontend
-connections, pty I/O and file watches. The frontend socket is
-`pardes-detached-<name>.sock` beside the session's 9P socket; a second
-session cannot take a live name. Up to 32 frontends attach; frames go to
-every one, while clipboard reads, browser opens and #word("Detach") go to
-the frontend that asked (else the first attached). Frames are full grids
-or changes against what each frontend last received, never queued: a
-frontend with unsent bytes skips that frame, and one that stops draining
-past 1 MiB of control backlog is closed, its peers untouched. Frontends
-never spawn shells, write session files or watch files. #word("Attach")
-connects first and swaps second: only after the handshake does a shell
-give up its own core. #word("Restore") builds the replacement core before touching
-the current one.
+One `pardes --daemon` per user (`src/daemon.zig`) listens on
+`pardes-daemon.sock` in the runtime directory, its `.lock` flocked for its
+life; the first session that finds none starts it (a double fork and an
+exec) and it exits a second after it holds nothing. It is nobody's parent:
+a session registers on one connection, sends it a dup of every pty master
+it forks (so a session killed outright never hangs its shells up, and
+#word("Adopt") takes them into another), says whether a terminal or a
+window shows it, and is handed a terminal (`pardes --attach`) or a window
+request (`pardes-gui --attach`) through it. Messages are `SOCK_SEQPACKET`
+datagrams: a line of words and the fds it carries.
-`src/detached/wire.zig` is the versioned protocol (version 10): fixed-width
-little-endian fields, a 5-byte header (tag, then a u32 length), payloads up
-to 16 MiB and grids up to 512 by 128. A comptime hash of `pardes.Chrome`
-forces a version bump when that struct changes.
+`pardes` in a terminal forks its session off before anything starts: the
+session, in a session of its own (`setsid`), draws on the terminal it
+opened, and the process the shell waits on stays as its stub, passing it
+`SIGWINCH`, `SIGTERM`, `SIGINT` and `SIGQUIT` and ending with its status.
+#word("Detach"), or the terminal's end (EIO, a hangup), puts
+the terminal back and lets it go; the stub ends (exit 0) and the session
+runs on with nothing drawn, until `pardes --attach` hands it another
+terminal. A window's #word("Detach") closes the window and keeps the
+process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the
+snapshot harness) runs a session as before the daemon: in the terminal's
+own process, ended by its hangup.
+
+A replica (a client running its own copy of the core, phase 5 of
+`docs/next-daemon.md`) connects to `pardes-replica.sock`, a stream socket
+beside it that `ssh -L` can forward. `src/detached/wire.zig` is its
+protocol (version 14): fixed-width little-endian fields, a 5-byte header
+(tag, then a u32 length), the hello, a ping, the input events. The hello
+names a session and carries the client's semantics hash (the protocol,
+release, commit, platform, build options and every dependency's hash); the
+daemon refuses another build's, or a session nobody has, in words, and
+hands an accepted connection to its session (`SCM_RIGHTS`), which welcomes
+it and from then on is the one it talks to. Today the session answers
+pings and nothing more.
+
+#word("Upgrade") (`src/upgrade.zig`) execs the path the session was started
+from, at a step boundary, after asking it `--version`: the session's dump
+goes to the DumpDir (`pardes-upgrade-<pid>.dump`), and its pty masters,
+terminals, stubs and daemon link stay open across the exec, named in a
+record on the new command line (`--upgraded=`) ahead of the arguments it
+was started with. The pid stays, so the shells stay its children; the new
+process loads the dump with every view and takes the fds back. One that
+cannot load it execs the old binary again (kept open from
+`/proc/self/exe`), or with none starts afresh with the shells adopted and
+the dump left for a Restore. The daemon re-execs the same way, its
+registry on its command line. `python3 -B test/daemon.py --upgrade <old>
+<new>` (and `--upgrade --gui`) is the end-to-end test.
= 9P