Skip to content

Contributing

This page is for people working on kolinsky itself, with a checkout of its source tree. The file CONTRIBUTING.md at the root of the tree holds the same notes plus the maintainer tasks: building this website, reproducing the benchmark and conformance numbers, and releasing.

Building

You need a stable Rust toolchain and the C compiler Cargo finds by default (the TLS code of the HTTP client compiles a few C files). The tree is one Cargo workspace:

cargo build --release -p kolinsky-cli    # the command line: target/release/kolinsky
cargo build --release -p kolinsky        # the library

The Python package is built with maturin from the python directory: maturin develop --release installs it into the active virtual environment, maturin build --release writes a wheel.

Tests

cargo test --workspace

runs the unit tests of every crate, the scenario suite, the examples of this website, the Python smoke test (skipped without a Python 3.9+ interpreter) and the performance budget tests (they build the release binary first). The scenarios that compare text widths and rasters expect a fixed set of fonts installed on the system: DejaVu, Liberation, FreeFont, Noto, Noto CJK, Noto Color Emoji, IPA Gothic, TLWG Loma, URW base35 and WenQuanYi Zen Hei. Raster comparisons use Ghostscript (gs) when it is installed. KOLINSKY_PERF_FACTOR scales the time budgets on slower machines.

The scenario suite

The behaviour of the engine is written down in two places:

  • specs/*.md: one file per area (tables, flex, fonts, paged media, PDF output, the public API and so on), made of numbered rules such as TB-12 or API-31;
  • specs/features/*.feature: executable Gherkin scenarios, each tagged with the rule it proves. Each scenario holds a small HTML document and checks the boxes of the layout, the text, the pixels of a page or the objects of the PDF.

The runner in tests/steps executes the scenarios against the engine. Every step phrase is defined once, in specs/features/STEPS.md; python3 specs/features/check_steps.py checks that every step line of the feature files matches exactly one phrase. Run a part of the suite with:

KOLINSKY_STEPS_FEATURES=tables,flex cargo test -p kolinsky-steps-tests              # some feature files
KOLINSKY_STEPS_FILTER="margin box" cargo test -p kolinsky-steps-tests               # scenarios by name

tests/steps/baseline.txt lists the scenarios that must pass. A scenario that passed once may not fail again; after making more scenarios pass, rewrite the list with KOLINSKY_STEPS_UPDATE_BASELINE=1.

Adding a scenario

  1. Find the rule in specs/<area>.md that states the behaviour. A behaviour without a rule needs the rule first.
  2. Add the scenario to the feature file of the area, tagged with the rule id, with the document inline: set @page { size: ...; margin: 0 } and reset the margins you do not test, so every expected number follows from the document alone. Write lengths in pt (1 px = 0.75 pt) and say in a comment how they are computed.
  3. Use only phrases of specs/features/STEPS.md and run check_steps.py. A new phrase is added to STEPS.md and implemented in tests/steps/src/steps.
  4. Run the scenario, then the whole feature file, and update the baseline when it passes.

Code layout

The workspace has small crates that depend downward only, so that they compile in parallel:

Crate What it holds
kolinsky-core atoms, arenas and ids, units, the diagnostics sink, the error type
kolinsky-unicode Unicode tables and algorithms: bidi, line breaking, grapheme and word clusters, scripts
kolinsky-html the HTML tokenizer and tree builder, the DOM
kolinsky-css the CSS parser, selectors, at-rules, the property tables, the cascade and computed values, counters
kolinsky-fonts font file reading, the font index and matching, @font-face, metrics, subsetting
kolinsky-text itemization, bidi, shaping, line breaking, hyphenation, justification
kolinsky-layout the box tree; block, inline, float, table, flex, grid, multi-column and positioned layout; pages, margin boxes, footnotes, fragmentation
kolinsky-image image decoding
kolinsky-draw painting: the laid-out pages to display lists
kolinsky-pdf the PDF writer: fonts, images, annotations, outline, tags, metadata
kolinsky-geometry a dump of the layout's boxes, used by the tests
kolinsky the public library: Engine, options, Document, fetchers
kolinsky-cli the kolinsky command line
kolinsky-pdfread a small PDF reader used by the tests
bench-* measurement crates, not shipped

The Python package lives in python/ (a PyO3 extension and the typed kolinsky package), the scenario runner in tests/steps, the performance budgets in tests/perf, the benchmark and conformance tools in bench/, and the generators of the Unicode tables in tools/. ARCHITECTURE.md describes the pipeline, the data model, the text stack, fragmentation, the PDF writer and the budgets in detail.

This website

The pages are in docs/. Pages under Reference, the benchmark and conformance figures and llms.txt are generated by the scripts in docs/scripts/; edit their sources, not the pages. Every Rust, Python and kolinsky command block of the pages is a file in docs/examples/ that the tests run, so a change of the API that breaks an example fails cargo test.