diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 11:07:09 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 11:25:35 -0300 |
| commit | 6b3df3071d16153bd554462c4f54ebb88f3ed50e (patch) | |
| tree | 5428c2d4d6679fe0c34c0496cd58f94fad1b7486 /docs | |
| parent | a953f560f648e91dda8dd3a8dafe60a7f75739d0 (diff) | |
| download | pardes-6b3df3071d16153bd554462c4f54ebb88f3ed50e.tar.gz pardes-6b3df3071d16153bd554462c4f54ebb88f3ed50e.zip | |
lib: pardes's syntax is a library, as ghostty-vt is ghostty's: a package that depends on pardes is given build.zig's `library` and nothing of the editor, one module, `pardes-syntax` (src/lib_syntax.zig), naming what a program that draws source text itself takes, the editor's own code under its own names (highlightFileRange and analyzeSource for a Syn a byte and the sticky headers' declarations, parse and walkNodes over the tree-sitter bindings, theme, page, ink and synInk for a named theme's colours, the line arithmetic, pathFor for a language's name); every dependency but tree-sitter's runtime is lazy in the manifest, so such a package fetches the runtime and the grammars of its tree-sitter set alone, and pardes's own build asks for all it is missing in one round before its first b.dependency; build.zig's tree-sitter and theme-generator blocks become treeSitter and generatedThemes for both to call, a grammar not yet fetched asked for and left out of that round, and the scanners' -include of src/tree_sitter_heap.h is spelled from the root package's directory, where the compiler runs (pardes's own flags are as they were); File.synStyle's switch moves to colors.synInk, so the editor and the library colour a class from one place; test/lib is such a package, depending on pardes by path: it colours, outlines and walks a C and a Zig source in orchard's colours under the testing allocator, and `zig build lib-test`, which unit-test runs, is its own `zig build test` over this checkout's zig-pkg; ts_markdown is pinned by the commit its hash is of (a0a00f81): its split_parser branch moved to v0.5.4 and a fresh fetch no longer matched; building.typ and the changelog say so; syntax snapshots unchanged
Diffstat (limited to 'docs')
| -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/), |
