# 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:

```bash
cargo build --workspace
```

Or using the `just` shortcut:

```bash
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:

```bash
cargo build --workspace --release
```

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

```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

```bash
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:

```bash
cargo test --workspace -- --test-threads 1
```

To run tests for a single crate:

```bash
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](../wire-format/overview.md).

---

## 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:

```bash
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:

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

---

## Next steps

- [Running the Server](running-the-server.md) -- start the server endpoint
- [Running the Client](running-the-client.md) -- CLI subcommands and usage examples
- [Docker Deployment](docker.md) -- build and run in containers