capnpc-embedded
Compile Cap'n Proto schemas from your build.rs with no system capnp
installation and no C/C++ toolchain — only a Rust toolchain.
The Cap'n Proto schema compiler is embedded as a single, architecture-independent WebAssembly module and executed in-process by a pure-Rust WASM engine. No subprocess, no native binary to install, and no network access at build time.
This crate is a sidecar: it only runs the compiler and hands you back the raw
CodeGeneratorRequest. You feed that to your own capnpc, so it does not
depend on — or pin the version of — capnpc/capnp. Pick whatever capnp
runtime your project uses. See capnproto-rust issue
#182 for background.
Usage
# Cargo.toml
[]
= "0.2"
= "0.20" # your choice — this is what the generated code targets
[]
= "0.20"
// build.rs
// src/main.rs
CompileCommand mirrors the capnp compile flags (file, src_prefix,
import_path, no_standard_import). Code-generation options — output
directory, parent module, etc. — live on your capnpc
CodeGenerationCommand, not here.
The standard import schemas — including rust.capnp for the capnpc-rust
annotations ($Rust.parentModule, $Rust.name, ...) — are bundled, so
import "/capnp/rust.capnp"; works out of the box.
Why WebAssembly?
Shipping precompiled native binaries is fragile — musl vs glibc, NixOS's
/nix/store + patchelf, and per-arch matrices (exactly the concerns raised in
issue #182). A single .wasm sidesteps all of it: the same artifact runs
identically on Linux (glibc and musl), macOS, and Windows, on any CPU
architecture, with no toolchain and no network. It is verified in CI on
linux-glibc, Alpine/musl, macOS, and Windows.
Versioning
Versions are X.Y.Z+A.B.C:
X.Y.Z— this crate's own SemVer (its API and packaging).+A.B.C— the bundled Cap'n Proto compiler version (informational).
Cargo ignores build metadata for version resolution, so:
- Every release bumps the
X.Y.Zpart; the+A.B.Csuffix is never the sole difference between two published versions. - Pin the SemVer part (
capnpc-embedded = "0.2"); you cannot pin "whatever bundles capnp 1.4". To pin an exact compiler, pin the exact crate version (=0.1.0) and read the metadata.
We follow SemVer for the crate itself. A new bundled capnp that is backward-compatible is a patch/minor bump; one that changes generated output in a breaking way (or an API break) is a breaking bump.
How the wasm is built
assets/capnp.wasm is generated, not committed to git. ci/build-wasm.sh
downloads the pinned pristine capnproto release, applies a small
__wasi__-guarded patch (patches/wasi-<version>.patch, ~9 files), and builds
with wasi-sdk + CMake to wasm32-wasip1. The compiler is built without C++
exceptions (-fno-exceptions), so the result is a plain MVP wasm that runs on
any engine.
We do not vendor capnproto's source — only that patch. The release pipeline runs
build-wasm.sh before cargo publish, so the published crate on crates.io
already contains the prebuilt wasm; consumers never run wasi-sdk or cmake.
See docs/architecture.md for the full design: the WASI
filesystem/path model, the wasmi engine and MVP-module constraints, and the
compiler patch.
Developing
The wasm isn't in git, so a fresh checkout must produce it once:
Platforms
Linux (glibc and musl), macOS, and Windows, on any CPU architecture — the same WebAssembly artifact everywhere. Every platform is exercised end-to-end in CI (including Alpine/musl).
Limitations
- Schema files and their imports must live on the local filesystem (they do, for a normal build). The compiler runs with a read-only view of the filesystem.
- On Windows, all input schemas/imports must be on a single drive (the current directory's drive) — normal for a project build.
- Only the schema-compile path is supported (external
capnpcode-generator plugins are not — butcapnpcgenerates Rust in-process, so this is not a limitation for Rust codegen).
License
MIT — see LICENSE.
This crate bundles and redistributes MIT-licensed components from Cap'n Proto
(the capnp.wasm compiler and the standard capnp/*.capnp schemas) and
capnproto-rust (rust.capnp). Their copyright notices are reproduced in
THIRD-PARTY-NOTICES.md.