diff options
Diffstat (limited to 'docs/typ/reference.typ')
| -rw-r--r-- | docs/typ/reference.typ | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 72d0b5ee..205b0400 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -34,6 +34,7 @@ ctl settings and session builtins @ro commands every builtin, one a line @other-files recent files opened lately: open|closed <path> @other-files dumps the dumps the state file keeps: label date size panes @other-files +addons the kinds of pane here, compiled in or an addon's @addons layout a line per column, then active <serial> @columns-and-tags tag the workspace tag @columns-and-tags tagexec a word clicked in the workspace tag @columns-and-tags @@ -970,6 +971,49 @@ at 200, ending in `…`. Control characters become spaces. synthetic. Linux v9fs's truncation `mtime` hint is accepted and dropped. - #file("/src/") with `-Dembed-sources=true`. += Addons <addons> + +An addon is a shared library that brings one kind of pane: a picture, a +game, a plot. It is written against one header, `src/kinds/pardes_addon.h`, +in C or anything that speaks C, and links nothing of pardes: the records +are the header's, and what pardes does for it (an allocation from the +pane's arena, a job off the loop, a Look, a message, a new text pane) it is +handed at load. `addons/fake/fake.c` uses every function; a kind with only +a head and `paint` is a valid one. Image is a kind compiled in, through the +same records. + +- #word("Addon") `load <path>` (relative to the pane's directory) loads + one; `unload <name>` lets one go, refused while a pane of its kind is + open; `reload <name>` loads its library again, every pane of the kind + kept through its `dump` and `load` (one with none comes back fresh), and + a library that fails any check leaves the old one running; bare, it says + the kinds here. At start, every `*.so` of `$XDG_DATA_HOME/pardes/addons`, + then of `<prefix>/lib/pardes/addons`, is loaded. +- #file("/addons"): a line a kind, `<kind> <version> <abi> static|loaded + <path>`, and a line an addon refused, with why: another ABI's major, no + `pardes_addon`, a word, leader path or extension already someone's (the + core's or another addon's: refused whole), words with no `ctl`. +- Its words join #file("/commands") and Help, `(addon <name>)` after each. + Written to a pane of its kind they go to that kind; a word that opens its + kind opens a pane of it from anywhere, its argument the path; any other + elsewhere is refused. A Look of a file whose extension an addon claims + opens a pane of its kind. +- A pane of an addon's kind takes every key but #key("Esc") when its kind + takes keys, as a raw terminal does, and its clicks when it takes the + mouse. Its #file("body") is the kind's text, if it has any; its + #file("ctl") read ends with the kind's own fields. +- A dump keeps each such pane: its kind, version, path and place, and the + kind's own record. Restored without its addon, the pane waits in its + place saying `addon <name> <version> is not loaded: Addon load <path>`; + the addon loaded, it opens there. +- An addon runs in pardes's process. A load is marked on disk while it + runs; a start that finds the mark of one that never finished skips that + library, listed so, until #word("Addon") `load` asks for it again. A + crash inside one says `in addon <file>, <call>` in the crash record. +- `pardes --addon-test <lib> <script>` runs a script of keys, clicks, + words and ticks against a pane of its kind and prints the pane after + each: an addon's test, compared with `diff`. + = The pardes command <command-line> In a pane's shell (`PARDES_PID`, `PARDES_9P` and `PARDES_PANE` set), |
