niso-compose

From the repository

This page is crates/niso-compose/CONTRACT.md, included when the site is built. Edit it there.

Purpose

The build-time helper that composes niso’s C runtime header (niso_runtime.h) and JS glue (glue.js) from sections that each belong to one crate (architecture.md 6 and 7, migration step 6). It has no niso dependency and runs only in build scripts and xtask.

Public surface

• MANIFEST: crates/niso-compose/sections.txt, which names each section of the two files, its owner crate and its anchor, and each file’s composition order.
• blocks(manifest) parses a manifest; block(name) is a block of MANIFEST.
• Block::split(text) cuts a monolith into its sections; Block::source is where a section lives after the cut-over; Block::read(root) reads the sections from there.
• Split::compose and Split::ordered: the composed file and its order.
• compose(name, root), for build scripts: the composed file, from the sections’ files (or from the monolith on a branch that predates the cut-over); it prints the cargo::rerun-if-changed lines for what it read.
• same_lines(a, b): whether two texts have the same lines in any order.

Guarantees

1. Sections cover the monolith: every line is in exactly one section, so concatenating the sections in the monolith’s order gives the monolith byte for byte, and a composition in another order has the same lines (unit tests; over the real section files, one checks that they still cut at their anchors into themselves, which resplit relies on).
2. A section starts at its anchor, the start of a line at column 0 after the previous section’s anchor, or at the comment right above that line. A missing anchor is an error that names the manifest line; nothing is assigned silently.
3. Composition order is the manifest’s: order file keeps the monolith’s; a list of owners gives head, each owner’s sections in that order (each owner’s in the monolith’s order), then tail.
4. After the cut-over a section lives in its owner’s tree (crates/<owner>/include/<section>.h or glue/<section>.js), in niso-core’s while the owner crate does not exist, in bindings/js/glue for the glue core, and in crates/niso-compose/frame for the composition’s own sections. A missing file is an error naming the section.

May assume from dependencies

None; it uses std only.

Differences from architecture.md 6

The architecture’s composition reads each crate’s fragments from Cargo links metadata (DEP_*). Until a crate brings its own IDL (step 6c) and its glue is a module with install(ctx), the manifest stands in for that metadata: it is the one list of sections and owners, and the glue keeps the monolith’s order because its statements run in order.

Standalone use

niso_compose::compose("header", &workspace_root) in a build script; cargo xtask split to see the sections and check them.