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

Building from Source

This page covers compiling the workspace, running the test suite, and the just convenience commands available for common development tasks.

---

Building the workspace

From the repository root:

cargo build --workspace

Or using the just shortcut:

just build

This compiles all nine crates in the workspace:

Crate	Type	Purpose
quicprochat-core	library	Crypto primitives, MLS GroupMember state machine, hybrid KEM
quicprochat-proto	library	Protobuf schemas (prost), generated types, method ID constants
quicprochat-kt	library	Key Transparency Merkle log
quicprochat-plugin-api	library	#![no_std] C-ABI plugin interface (HookVTable)
quicprochat-rpc	library	QUIC RPC framing, server dispatcher, client, Tower middleware
quicprochat-sdk	library	QpqClient, event broadcast, ConversationStore
quicprochat-server	binary	Unified Authentication + Delivery Service (qpc-server)
quicprochat-client	binary	CLI client (qpc) with REPL and subcommands
quicprochat-p2p	library	iroh P2P layer (compiled when the mesh feature is enabled)

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"

---

just commands

A justfile at the repository root provides shortcuts for common tasks:

Command	Equivalent	Description
just build	cargo build --workspace	Build all crates
just test	cargo test --workspace	Run full test suite
just lint	cargo clippy --workspace -- -D warnings	Check for warnings (CI-strict)
just fmt	cargo fmt --all -- --check	Check formatting
just fmt-fix	cargo fmt --all	Auto-format
just proto	cargo build -p quicprochat-proto	Trigger Protobuf codegen
just rpc	cargo build -p quicprochat-rpc	Build RPC framework only
just sdk	cargo build -p quicprochat-sdk	Build client SDK only
just server	cargo build -p quicprochat-server	Build server only
just client	cargo build -p quicprochat-client	Build CLI client only
just clean	cargo clean	Remove build artifacts

---

Running the test suite

just test
# or
cargo test --workspace

The E2E tests use a shared AUTH_LOCK mutex to prevent port conflicts. Run them with a single thread to avoid flaky failures:

cargo test --workspace -- --test-threads 1

To run tests for a single crate:

cargo test -p quicprochat-core
cargo test -p quicprochat-server
cargo test -p quicprochat-rpc

---

Protobuf code generation

The quicprochat-proto crate does not contain hand-written Rust types for wire messages. Instead, its build.rs script uses prost-build to generate Rust source from the .proto schema files in proto/qpc/v1/.

How it works

1. build.rs invokes prost_build::Config::new() on the 11 schema files under proto/.
2. prost-build locates the protoc binary via the protobuf-src crate, which compiles and vendors a compatible protoc binary at build time. No system installation of protoc is required.
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"), "/...")) macros.

Rebuild triggers

The build.rs script emits cargo:rerun-if-changed directives for each .proto file. Modifying a schema triggers automatic re-generation on the next cargo build.

Design constraints of quicprochat-proto

The proto crate is intentionally restricted:

• No crypto -- key material never enters this crate.
• No I/O -- callers own the transport; this crate 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

Slow first build

The first build downloads and compiles all dependencies (including openmls, quinn, rustls, prost-build, protobuf-src, etc.). This can take several minutes depending on your hardware. The protobuf-src compilation step is the most time-consuming on a cold cache. Subsequent builds are incremental and much faster.

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

E2E tests failing with port conflicts

Run E2E tests with --test-threads 1 to serialise the tests and avoid bind conflicts on the shared test port:

cargo test -p quicprochat-client --test e2e -- --test-threads 1

---

Next steps

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