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¶
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 asTB-12orAPI-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¶
- Find the rule in
specs/<area>.mdthat states the behaviour. A behaviour without a rule needs the rule first. - 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. - Use only phrases of
specs/features/STEPS.mdand runcheck_steps.py. A new phrase is added toSTEPS.mdand implemented intests/steps/src/steps. - 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.