diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 00000000..daeac183 --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# pardes + +A text environment in the acme tradition: columns of panes, each pane a tag line +plus a body, where the body is a live terminal, a file, an image, or a PDF. The +mouse carries meaning — left selects, middle executes, right looks — and +everything on screen is text that is equally alive, whether a shell printed it or +you typed it. + +One program, five thin shells. The core is a library in the way ghostty-vt is a +library: you feed it events, it returns a surface and a list of effects, and it +performs no IO itself. Everything a shell does is translate native input into +`pardes.Event`, render `pardes.Surface`, and perform `pardes.Effect`. + +## Requirements + +Zig **0.16.0** (`build.zig.zon` pins `minimum_zig_version`). Dependencies are +fetched and pinned by the manifest; no system package is required for the +terminal build. The SDL shell builds SDL3 and FreeType from source. Native PDF +support builds MuPDF and is on by default (`-Dmupdf=false` to drop it). + +## Build + +``` +zig build +``` + +That is the whole of it, and it is an *install*: it builds both native shells and +puts them in `~/.local/bin`. + +``` +~/.local/bin/pardes the terminal shell (libvaxis) +~/.local/bin/pardes-gui the SDL3 window +``` + +Override with `--prefix <dir>`. Six development binaries install under +`<prefix>/dev` so they never land on a `PATH` by accident: `perf`, +`fs-bench`, `lspbench`, `pdf-scroll-bench`, `hxdiff` and the isolated build. +The other steps below build what they need and install nothing. + +``` +pardes --version e.g. pardes 0.0.1 (e61bbb2e86bd) +pardes --help every flag +``` + +The version comes from `build.zig.zon`'s `.version`; the commit is read from +`git` at configure time and is simply absent when there is no repository to ask. + +## The five platforms + +| build | what it is | +|---|---| +| `zig build` | the terminal shell and the SDL window, together | +| `zig build -Dplatform=tty` | the terminal shell alone | +| `zig build -Dplatform=gui` | the SDL3 window alone | +| `zig build web` | a freestanding wasm core plus vanilla JavaScript, rendered as HTML/CSS | +| `zig build -Dplatform=macos` | an AppKit and CoreText app over a static `libpardes.a` | +| `zig build -Dplatform=esp32p4 -Desp32p4-firmware` | firmware for an ESP32-P4: a freestanding riscv32 object driving libvaxis down a UART, in 384 KiB of heap | + +The board build needs an ESP-IDF checkout for its register headers, and adds +`esp32p4-flash`, `esp32p4-attach`, `esp32p4-run`, `esp32p4-reset`, +`esp32p4-image-size`, `esp32p4-image-check` and `esp32p4-test`. + +## Detached sessions + +A shell need not be in the same process as the core. + +``` +pardes --detach=work a core with no terminal of its own +pardes --attach=work become a frontend of it +pardes-gui --attach=work ...the SDL window can attach too +``` + +Several frontends may be attached at once and all see the same screen. The +detached core performs every effect that needs a disk or a process table, so its +pane shells outlive every frontend; a frontend keeps only what needs the human's +own display. From inside the editor, `Attach` and `Detach` do the same thing as +words. See `docs/detached.md`. + +## Tests + +``` +zig build unit-test module and shell unit tests +zig build snap scripted input traces against frozen golden grids +zig build hxdiff differential suite against helix's own behaviour +zig build hxparity file-pane vs pty-pane editing parity +zig build mupdf-check compile, link, render and search docs/design.pdf +zig build web-snap browser touch/LOOK snapshots +zig build web-e2e Chrome-driven DOM end-to-end suite +``` + +`snap` and `hxdiff` take `-- --update` and explicit case files respectively. The +benchmark steps — `perf`, `pdf-bench`, `pdf-scroll-bench`, `pdf-sections-bench`, +`lspbench`, `fs-bench` — all accept `-- --json`. + +## Documentation + +`docs/design.pdf` (from `docs/design.typ`) is the architecture document and the +place to start. It is also a test fixture: `mupdf-check` renders and searches it. + +| file | subject | +|---|---| +| `docs/design.typ` | architecture: the seams, the data model, the build graph | +| `docs/detached.md` | one core, many frontends, over a unix socket | +| `docs/config.md` | build options and runtime configuration | +| `docs/acme-fs.md` | the acme control filesystem (`--fs`) | +| `docs/lsp.md` | the in-process ZLS backend | +| `docs/lsp-evaluation.md` | why that backend, measured against the alternatives | +| `docs/helix-keys.md` | the helix-compatible key model and its differential suite | +| `docs/macos.md` | the native macOS shell, its bundle and its signing | +| `docs/web.md` | the browser shell | +| `docs/ghostty-macos-notes.md` | notes on the ghostty dependency | +| `docs/ideas.typ` | scratch notes; nothing compiles it, and it says so | + +`next-steps.txt` is a wishlist with a status header saying which items have +shipped; `transactions.txt` records one open structural gap against helix, and +says which waiver proves it is still open. + +## Layout + +``` +src/ the core (pardes.zig) and one module per platform +src/detached/ the wire, the detached core, the frontend client +src/lsp/ the in-process language backend +test/ harnesses, snapshot goldens, helix cases +build/ build-time helpers (the snapshot suite) +docs/ see above +``` |