Headless Blitz rendering behind a C ABI, built as libblitz.a for static
linking from C, or from any language with a C FFI. Language bindings live in
their own repos and consume the staged artifacts from make dist.
Derived from examples/screenshot.rs. Same pipeline — HtmlDocument →
resolve → paint_scene into VelloCpuImageRenderer — with the CLI parsing,
timing printouts and manifest-relative output path replaced by an FFI surface.
Standalone repo — nothing needs to be added to the Blitz workspace.
Cargo.toml
Makefile
.gitignore
include/blitz.h
src/lib.rs
src/markdown.rs
examples/c/screenshot.c # renders a URL to a PNG
examples/c/render.c # renders a URL, .html file, or .md file
.github/workflows/ci.yml # three-OS matrix
scripts/update-pins.sh # repin the git dependencies
tests/render_to_disk.rs # renders real PNGs you can look at
Build products (target/, build/, dist/) are gitignored. Cargo.lock is
not — with git-pinned dependencies, the lockfile is what makes a given
libblitz.a reproducible.
make runBuilds the static library, discovers the system libraries a static link needs,
compiles examples/c/screenshot.c against it, and renders
https://www.google.com to google.png at 1200 CSS px / 2x.
Override any of it:
make run URL=https://example.com OUT=example.png WIDTH=1400
make run PROFILE=production # LTO'd, stripped
make native-libs # just print the link flags
make dist # stage artifacts for other languagesThe second example takes any of the three input kinds and dispatches on it:
make render INPUT=README.md # -> README.png
make render INPUT=docs/index.html # -> index.png
make render INPUT=https://example.com # -> examplecom.png
make render INPUT=README.md OUTPUT=doc.png WIDTH=900It decides by looking at the input: scheme:// means fetch it as a URL,
a .md/.markdown/.mdown/.mkd extension means markdown, and anything else
is treated as HTML. Local files are read directly and given a file:// base URL
for their containing directory, so relative <img src> and stylesheet paths
resolve — that requires enable_net to stay on, since assets go through the net
provider even for local documents.
Note that file:///path/to/x.html and ./x.html both work but take different
paths through the library: the first is fetched by blitz_render_url, the second
is read by the example and passed to blitz_render_html.
The first build is long — Stylo, parley and rustls all compile from source.
Blitz and AnyRender are both pinned to a revision:
dioxuslabs/blitz@b78db85dioxuslabs/anyrender@562c03e
The five blitz-* crates share one git source and rev, so they resolve to a
single checkout. Splitting them across revs produces two copies of
blitz-traits and a wall of trait-mismatch errors.
AnyRender is handled differently, and the difference matters. It's declared
against crates.io in [dependencies] and redirected by [patch.crates-io].
A direct git dependency would not work: blitz-paint depends on anyrender
from crates.io, so a git dep here would put two distinct anyrender crates in
the graph — PaintScene from one isn't PaintScene from the other, and
paint_scene(scene, ...) stops compiling. Patching rewrites the crates.io
source graph-wide, blitz-paint included.
This is also why the crate declares an empty [workspace] table: cargo only
honours [patch] in a workspace root manifest.
Verify there's exactly one copy before you debug anything else:
cargo tree -i anyrender
cargo tree -i peniko
cargo tree -d # lists every duplicated crateIf cargo reports a patch as unused, or refuses the patch because the git
version doesn't satisfy 0.13.0, bump the version requirement in
[dependencies] to whatever the pinned rev actually declares.
cargo build --release
# -> target/release/libblitz.a (static)
# -> target/release/libblitz.so (shared, from the cdylib crate-type)For a smaller, faster artifact, use the production profile (LTO, one codegen
unit, symbols stripped):
cargo build --profile production
# -> target/production/libblitz.amake fmt # cargo fmt --all; CI rejects unformatted code
make test # unit tests only; hermetic, no network
make screenshots # renders tests/output/{readme,google}.pngtests/render_to_disk.rs drives the C entry points rather than the internal
Rust functions, so it doubles as a smoke test of the FFI surface — a drifting
signature or ownership rule fails here before any downstream consumer sees it.
It checks the PNG magic bytes and a minimum file size, since a status code of
BLITZ_OK doesn't tell you whether anything was actually painted; a blank page
usually means no fonts are installed.
The markdown test runs everywhere and disables networking. The google.com one
is #[ignore]d, because a test that fails on a train is a test people learn to
ignore — make screenshots passes --include-ignored to run it. Output lands
in tests/output/, which is gitignored.
.github/workflows/ci.yml runs four jobs:
- test — a matrix over
ubuntu-latest,macos-latestandwindows-latest. Builds the archive, checks for duplicatedanyrender/penikoin the tree, prints the native link flags, and runs the hermetic tests. - lint —
cargo fmt --check,cargo clippy -D warnings, the C examples rebuilt with-Werror, and shellcheck on the update script. - network — renders google.com for real.
continue-on-error: true, because it depends on an external site that can rate-limit or redirect datacenter IPs. A red mark there means "look at it", not "the code is broken". - pins — reports whether upstream has moved. Informational.
Two things about the matrix are worth knowing.
The C examples are skipped on Windows. render.c uses realpath,
strcasecmp and clock_gettime, none of which MSVC provides. The library and
blitz.h are portable; Windows still builds blitz.lib and runs the Rust tests,
which drive the same FFI entry points. Porting the examples would mean an
MSYS2/mingw toolchain or a pile of #ifdefs for no real coverage gain.
Linux and macOS runners install fonts explicitly. The renderer resolves fonts
through the host, and a fontless runner produces blank pages that still return
BLITZ_OK — so the workflow asserts a minimum PNG size rather than trusting the
status code. Rendered output is uploaded as an artifact on every run.
Windows additionally installs NASM, which aws-lc-rs (rustls' crypto provider)
needs to assemble its primitives.
Run make fmt before committing. The lint job fails on unformatted code.
make update-pins # both repos, latest default branch
bash scripts/update-pins.sh --check # exit 1 if out of date (for CI)
bash scripts/update-pins.sh --dry-run
bash scripts/update-pins.sh --branch main
bash scripts/update-pins.sh --blitz a1b2c3d # pin one repo exactlyIt resolves commits with git ls-remote, not the GitHub API, so it needs no
token and has no rate limit. Every rev belonging to each repo is rewritten,
including the commented-out [patch.crates-io] lines so they stay usable, and
it runs cargo fetch afterwards to confirm the new revisions actually resolve —
restoring the original Cargo.toml if they don't.
The thing most likely to break on an update is the [patch] version
requirements: if a new AnyRender revision bumps its version past 0.13, the
patch is rejected until you bump the requirement in [dependencies] to match.
The script says so when it happens.
If the exec bit didn't survive (zip extraction, git archive, some Windows
checkouts), either run it through bash as above or chmod +x scripts/update-pins.sh.
The TLS backend is selected by a feature:
cargo build --release # tls-aws-lc (default)
cargo build --release --no-default-features --features tls-ring # ring insteadBoth are pure-Rust stacks in the sense that matters: neither links OpenSSL,
neither needs a system TLS library at runtime, and roots are compiled in via
webpki-roots so the archive works in a scratch container. They differ only in
where the crypto primitives come from.
- tls-aws-lc — rustls with aws-lc-rs, reqwest's default. Fast, FIPS-capable, but aws-lc-rs compiles C and assembly, so building needs cmake and a C toolchain (plus NASM on Windows).
- tls-ring — rustls with ring, installed as the process default provider on
the first
blitz_context_new. Drops the cmake/NASM requirement. If you use this, confirm therustlsversion inCargo.tomlmatches what reqwest resolves to (cargo tree -i rustls) — a mismatch means the provider is installed into a different rustls than the one doing the handshake, and every connection fails at runtime with no obvious cause.
Selecting a rustls backend does not, by itself, keep OpenSSL out. Cargo unions
features across the whole dependency graph. Setting default-features = false
on reqwest here only speaks for this crate's own edge — if any other crate in
the tree enables reqwest/default-tls, native-tls comes back, and OpenSSL
appears in the link flags for everyone downstream.
In this graph the crate that does it is almost always blitz-net.
Find the culprit:
make check-tls
cargo tree -e features -i openssl-syscargo tree -e features -i prints the chain of features that pulled it in, which
names the crate and the feature responsible. The fix is to turn off that crate's
defaults and select its rustls option:
blitz-net = { git = "...", rev = "...", default-features = false, features = ["rustls"] }The exact feature name isn't stable across revisions, so check blitz-net's own
manifest in the checkout rather than trusting the snippet above.
If blitz-net offers no rustls option at all, no amount of configuration here
will help — feature unification gives a dependent no way to remove a feature.
That case needs a change upstream, or a [patch] pointing blitz-net at a fork
with the feature added.
make check-tls fails when openssl-sys is present, and CI runs the same check,
so once this is clean it stays clean.
The link flags change. Re-run make native-libs and update any consumer that
hardcodes them — in the Go bindings that's the #cgo LDFLAGS lines, which
currently carry -lssl -lcrypto for the Linux targets.
Note that -lfontconfig is a separate system dependency, from font enumeration
rather than TLS, and removing OpenSSL doesn't affect it.
This matters more than usual. A Rust staticlib does not bundle the system
libraries it depends on, and Blitz's dependency tree is deep — parley/fontique
for font enumeration, rustls + ring for TLS, tokio for I/O. Ask rustc rather
than guessing:
make native-libs
# equivalently:
cargo rustc --release --crate-type staticlib -- --print native-static-libsIt prints a line like -lgcc_s -lutil -lrt -lpthread -lm -ldl -lc. The Makefile
feeds this straight into the C link, so the examples need no manual step.
Consumers outside this repo do need it, and many build systems can't compute it
— cgo's #cgo LDFLAGS directives, for one, have to be literal. make dist
writes the list to dist/native-static-libs.flags so it can be copied or read
by a generator script. Getting it wrong produces undefined-symbol errors at link
time, not at runtime.
make go-lib
CGO_ENABLED=1 go build ./...${SRCDIR} in the cgo directives resolves relative to the Go source file, so
the lib/ and include/ directories live next to blitz.go and the package is
go get-able as a unit. Committing a 100+ MB .a to git is unpleasant, though —
for anything beyond a prototype, prefer a go:generate step or a Makefile that
builds the Rust side and copies the artifact in.
examples/c/screenshot.c is the reference:
BlitzContext *ctx = blitz_context_new(0);
BlitzRenderOptions opts = blitz_render_options_default();
opts.width = 1200;
opts.scale = 2.0f;
BlitzImage img = {0};
if (blitz_render_url(ctx, "https://www.google.com", &opts, &img) != BLITZ_OK) {
fprintf(stderr, "%s\n", blitz_last_error_message());
return 1;
}
blitz_image_write_png(&img, "google.png", 144);
blitz_image_free(&img);
blitz_context_free(ctx);Swap blitz_render_url for blitz_render_markdown(ctx, md, NULL, NULL, &opts, &img)
to render markdown instead; nothing else changes.
Note blitz_image_free, not free(). The buffer came from Rust's allocator and
carries its own capacity, so the host allocator can't release it.
make distProduces:
dist/lib/libblitz.a
dist/include/blitz.h
dist/native-static-libs.flags
That's everything a binding needs: the archive, the declarations, and the system
libraries the archive expects alongside it. Bindings (Go/cgo, Python/ctypes,
Node) live in their own repos and copy these in — typically via a release
artifact or a build step, since a libblitz.a is far too large to commit
comfortably.
Three rules any binding has to respect:
- Free with
blitz_image_free/blitz_buffer_free, never the hostfree(). The buffers come from Rust's allocator and carry their own capacity. - Read
blitz_last_error_messageimmediately after a non-zero return. It's thread-local and only valid until the nextblitz_*call on that thread. - Copy pixels out before freeing the image if the host language needs to own them.
One context, many renders. blitz_context_new spins up a tokio runtime with
worker threads. Create it once at process start. Renders are serialised behind an
internal mutex because Stylo keeps process-global style state and HtmlDocument
is not Sync; for real parallelism, run several processes rather than several
contexts.
Fonts. The CPU renderer resolves fonts through the host system. In a scratch
container with no fonts installed, text renders as blank boxes. Install at least
fontconfig and a font package (fonts-dejavu-core is enough) in any image that
runs this.
Panics don't cross the boundary. Every entry point is wrapped in
catch_unwind and returns BLITZ_ERR_PANIC with a message rather than
unwinding into Go, which would abort the process. This does rely on the build
using panic = "unwind". None of the profiles in Cargo.toml set
panic = "abort" — if you add one that does, abort turns every recoverable
render error into a dead host process.
Goroutine stacks. cgo calls run on an OS thread with a system stack, so the
renderer's recursion depth is fine, but a blitz_render_* call blocks that
thread for its full duration. Rendering is CPU-heavy; bound your concurrency
rather than firing one goroutine per URL.
Cross-compiling with cgo means a full cross toolchain for both Rust and C. Building inside the target container is almost always less painful.
I don't have the crates or a compiler here, so treat the following as the places
most likely to need a small fix on first build. All of them are lifted from
screenshot.rs, but the pinned revs are ahead of what I know:
DocumentConfig's field set —base_urlhere takesOption<String>directly, where the example passedSome(url_string).Provider::new(None)— signature and thenet_provider: Some(Arc::clone(&net) as _)coercion.Color::from_rgba8— the example only usedColor::WHITE; confirm the constructor name in the pinnedcolor0.3.Provider::is_emptyas the settle condition.pulldown-cmark0.13's API —Options::ENABLE_*flag names have shifted across releases, andENABLE_HEADING_ATTRIBUTESin particular is newer than the rest. Drop any flag the compiler doesn't recognise.- Whether the pinned AnyRender rev still declares
anyrender0.13 /anyrender_vello_cpu0.17. If not, the[patch]is rejected and the version requirements in[dependencies]need bumping to match. peniko0.6 — it has to agree with whatever the pinned Blitz and AnyRender revs resolve to.cargo tree -dwill show it if it doesn't.- Whether
blitz-dom'sdefaultfeature is the right one for a no-window build, or whether a narrower feature set drops the winit/wgpu paths entirely. Worth checkingblitz-dom's manifest in the pinned checkout — a smaller.ais a direct win here.blitz-paint's default features are worth a look too, since they decide whetheranyrender_svgjoins the graph and needs patching.