diff options
Diffstat (limited to 'docs/typ/building.typ')
| -rw-r--r-- | docs/typ/building.typ | 49 |
1 files changed, 47 insertions, 2 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ index f78f83a9..31019116 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -1,5 +1,5 @@ -// Building pardes, for contributors: platforms, options, tests, the -// release gates and sending patches, then how the pieces fit: the core +// Building pardes, for contributors: platforms, options, the library, tests, +// the release gates and sending patches, then how the pieces fit: the core // 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 @@ -71,6 +71,49 @@ must share with its session; `pardes --help` lists every flag. [`-Dhelix-harness`], [reference executable for live differential tests; `HX_HARNESS`, else `hx-harness` on `PATH`], ) +== As a library <library> + +A Zig package that depends on pardes is given one module and nothing of +the editor: `pardes-syntax` (`src/lib_syntax.zig`), for a program that +draws source text itself and wants it parsed and coloured as pardes has +it. + +``` +// build.zig.zon +.pardes = .{ .path = "../pardes" }, +// build.zig +const pardes = b.dependency("pardes", .{ + .target = target, + .optimize = optimize, + .@"tree-sitter" = .minimal, +}); +exe.root_module.addImport("pardes-syntax", pardes.module("pardes-syntax")); +``` + +It is the editor's own code under the names it has there. A language is +told by a path's extension, as in the editor, and `pathFor` gives a path +for a language's name. + +#pairs( + [`highlightFileRange`, `analyzeSource`], [a style class for each byte (`Syn`: keyword, string, number, comment or none) and the declarations the sticky headers show, each with its bytes and lines], + [`parse`, `walkNodes`, `ts`], [a text's syntax tree, helix's walks from a byte range to the node about it, its siblings and children, and the tree-sitter bindings the nodes are read through], + [`theme`, `themes`, `page`, `ink`, `synInk`], [a theme by name and what it draws a page, its text and each class in], + [`lineCount`, `lineStartOffset`, `lineSlice`], [a line's bytes from its number], + [`grammars`, `supportsPath`, `pathFor`], [every grammar, and whether this build has a path's], + [`start`, `stop`], [tree-sitter's allocator, and the end of the parsers kept per language], +) + +The `tree-sitter` option is the build's own: `zig`, `minimal` (C, C++ +and Zig) or `full`, the default. Every dependency but tree-sitter's +runtime is lazy in the manifest, so the package fetches the runtime and +its set's grammars and compiles those alone; pardes's own build asks for +what it is missing in one round. Zig still unpacks a lazy package whose +archive its global cache already holds; `--pkg-dir` (or `ZIG_LOCAL_PKG_DIR`) +at pardes's `zig-pkg` shares the one copy. What a pane measures stays +out: a cell's width is vaxis's and uucode's, and a tab is +`config.tab_width` cells wherever it stands. `test/lib` is such a +package, and `zig build lib-test` builds and runs it. + = Tests ``` @@ -85,6 +128,8 @@ zig build kitty-harness kitty graphics through a pane end to end (a fake kitt kitten icat and chafa too when installed) zig build syntax-test tree-sitter tests without building the editor zig build syntax deterministic per-byte highlighting snapshots +zig build lib-test the library, from a package that depends on pardes (test/lib); + unit-test runs it too zig build behaviour-test behaviour through the 9P tree, in process (test/behaviour/), and the T1 runner's short run of random 9P requests zig build process-test real sessions over their sockets: mounts, flags, shells (test/process/), |
