capnpc-embedded 0.2.0+1.4.0

Compile Cap'n Proto schemas in build.rs with no system capnp and no C/C++ toolchain — the capnp compiler is embedded as WebAssembly and run in-process.
Documentation

capnpc-embedded

crates.io docs.rs CI

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
[build-dependencies]
capnpc-embedded = "0.2"
capnpc = "0.20"          # your choice — this is what the generated code targets

[dependencies]
capnp = "0.20"
// build.rs
fn main() {
    // 1. Run the embedded compiler → raw CodeGeneratorRequest bytes.
    let request = capnpc_embedded::CompileCommand::new()
        .file("schema/foo.capnp")
        .src_prefix("schema")
        .compile()
        .expect("failed to compile capnp schema");

    // 2. Generate Rust with your own capnpc version.
    capnpc::codegen::CodeGenerationCommand::new()
        .output_directory(std::env::var("OUT_DIR").unwrap())
        .run(&request[..])
        .expect("failed to generate code");
}
// src/main.rs
mod foo_capnp {
    include!(concat!(env!("OUT_DIR"), "/foo_capnp.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.Z part; the +A.B.C suffix 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:

ci/build-wasm.sh   # needs cmake; downloads wasi-sdk
cargo test

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 capnp code-generator plugins are not — but capnpc generates 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.