Contributing to zigurine #

Issues and pull requests go to the Tangled mirror, https://tangled.org/jcollie.dev/zigurine.

Setting up #

Everything needed is in the Nix development shell: Zig 0.17, reuse, zon2nix and kcov.

$ nix develop
$ zig build test --summary all
$ zig build check           # compiles everything without running it

Before sending a change, make sure these pass, as CI checks them:

$ zig fmt --check .
$ reuse lint
$ zig build test
$ nix build

How it is put together #

File	What it does
src/main.zig	The command line, and the order things happen in: ask the terminal, load the font, draw, color, encode, send.
src/terminal.zig	The queries sent to the terminal, the parser for its replies, and the raw-mode wait with a timeout. The parser is a pure function, so the tests feed it bytes.
src/banner.zig	Shapes and draws the text in white, finds the size whose ink is exactly the height wanted, and crops to the ink.
src/rainbow.zig	OKLCH to sRGB with the chroma reduced into gamut, and the per-pixel recoloring.
src/kitty.zig	The kitty graphics escape codes for a PNG, base64 in 4096-byte chunks.
nix/module.nix	The NixOS module.

GLOSSARY.md holds the project's vocabulary, and docs/adr/ the decisions that would surprise someone reading the code.

The font libraries are all taken through zig-font-shaper's own dependencies (see build.zig), so that each is a single module. To move to newer versions, update the font_shaper pin in build.zig.zon with zig fetch --save=font_shaper <url>, then regenerate the Nix expression for the dependencies and commit both:

$ nix develop -c zon2nix --17 --nix=build.zig.zon.nix build.zig.zon

Trying the terminal path #

zigurine shows nothing unless it is talking to a terminal that answers the kitty graphics query: kitty, Ghostty, WezTerm, Konsole and others. -o FILE.png skips the terminal entirely and is the quickest way to see what a change does to the picture.

Licensing #

Code is MIT. Every file carries an SPDX header, or is covered in REUSE.toml when it cannot hold one.