Christian Nennemann
2e081ead8e
Rename all project references from quicproquo/qpq to quicprochat/qpc across documentation, Docker configuration, CI workflows, packaging scripts, operational configs, and build tooling. - Docker: crate paths, binary names, user/group, data dirs, env vars - CI: workflow crate references, binary names, artifact names - Docs: all markdown files under docs/, SDK READMEs, book.toml - Packaging: OpenWrt Makefile, init script, UCI config (file renames) - Scripts: justfile, dev-shell, screenshot, cross-compile, ai_team - Operations: Prometheus config, alert rules, Grafana dashboard - Config: .env.example (QPQ_* → QPC_*), CODEOWNERS paths - Top-level: README, CONTRIBUTING, ROADMAP, CLAUDE.md
154 lines
5.1 KiB
Markdown
154 lines
5.1 KiB
Markdown
# 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
|