quicproquo/docs/src/getting-started/building.md

Building from Source

This page covers compiling the workspace, running the test suite, and understanding the build-time Cap'n Proto code generation step.

---

Building the workspace

From the repository root:

cargo build --workspace

This compiles all four crates:

Crate	Type	Purpose
quicproquo-core	library	Crypto primitives, MLS GroupMember state machine, hybrid KEM
quicproquo-proto	library	Cap'n Proto schemas, generated types, envelope serialisation helpers
quicproquo-server	binary	Unified Authentication + Delivery Service (NodeService)
quicproquo-client	binary	CLI client with subcommands (ping, register, send, recv, etc.)

For a release build with LTO, symbol stripping, and single codegen unit:

cargo build --workspace --release

The release profile is configured in the workspace Cargo.toml:

[profile.release]
opt-level     = 3
lto           = "thin"
codegen-units = 1
strip         = "symbols"

---

Running the test suite

cargo test --workspace

The test suite includes:

• quicproquo-proto: Round-trip serialisation tests for Cap'n Proto Envelope messages (Ping, Pong, corrupted-input error handling).
• quicproquo-core: Two-party MLS round-trip (create_group / add_member / send_message / receive_message), group ID lifecycle assertions.
• quicproquo-client: Integration tests for MLS group operations and auth service interactions (require a running server or use in-process mocks).

To run tests for a single crate:

cargo test -p quicproquo-core

---

Cap'n Proto code generation

The quicproquo-proto crate does not contain hand-written Rust types for wire messages. Instead, its build.rs script invokes the capnp compiler at build time to generate Rust source from the .capnp schema files.

How it works

1. build.rs locates the workspace-root schemas/ directory (two levels above crates/quicproquo-proto/).
2. It invokes capnpc::CompilerCommand on all four schema files:
   • schemas/envelope.capnp -- top-level wire envelope with MsgType discriminant
   • schemas/auth.capnp -- AuthenticationService RPC interface
   • schemas/delivery.capnp -- DeliveryService RPC interface
   • schemas/node.capnp -- NodeService RPC interface (unified AS + DS)
3. The generated Rust source is written to $OUT_DIR (Cargo's build output directory).
4. src/lib.rs includes the generated code via include!(concat!(env!("OUT_DIR"), "/envelope_capnp.rs")) and similar macros for each schema.

Rebuild triggers

The build.rs script emits cargo:rerun-if-changed directives for each schema file. If you modify a .capnp file, the next cargo build will automatically re-run code generation.

Schema include path

The src_prefix is set to the schemas/ directory so that inter-schema imports (e.g., using Auth = import "auth.capnp".Auth; inside node.capnp) resolve correctly.

Design constraints of quicproquo-proto

The proto crate is intentionally restricted:

• No crypto -- key material never enters this crate.
• No I/O -- callers own the transport; this crate only converts bytes to types and back.
• No async -- pure synchronous data-layer code.

For details on the wire format, see the Wire Format Reference.

---

Troubleshooting

capnp binary not found

Symptom:

Cap'n Proto schema compilation failed.
Is `capnp` installed? (apt-get install capnproto / brew install capnp)

Fix: Install the Cap'n Proto compiler for your platform. See Prerequisites for platform-specific instructions.

Verify it is on your PATH:

which capnp
capnp --version

Version mismatch between capnp CLI and capnpc Rust crate

The workspace uses capnpc = "0.19" (the Rust bindings for the Cap'n Proto compiler). If your system capnp binary is significantly older or newer, generated code may be incompatible. The recommended approach is to use a capnp binary whose major version matches the capnpc crate version. On most systems, the package manager version is compatible.

linker errors on macOS with Apple Silicon

If you see linker errors related to ring or aws-lc-sys (used transitively by rustls), ensure you have Xcode Command Line Tools installed:

xcode-select --install

Slow first build

The first build downloads and compiles all dependencies (including openmls, quinn, rustls, capnp-rpc, etc.). This can take several minutes depending on your hardware. Subsequent builds are incremental and much faster.

---

Next steps

• Running the Server -- start the NodeService endpoint
• Running the Client -- CLI subcommands and usage examples
• Docker Deployment -- build and run in containers