============================================= CCC Rust — Developer Build Guide ============================================= :Last Updated: 2026-03-11 This document covers everything needed to build, test, and cross-compile the ``ccc_rust`` workspace on a development machine. ---- Prerequisites ============= The table below lists all required tools. Versions shown are known-good; newer patch releases should work. +------------------+---------------+--------------------------------------------------+ | Tool | Min Version | Purpose | +==================+===============+==================================================+ | **Rust (rustup)**| stable 1.85+ | Compiler toolchain (pinned via ``rust-toolchain`` | | | | ``.toml``) | +------------------+---------------+--------------------------------------------------+ | **CMake** | 3.24+ | Builds vendored wolfSSL from source | +------------------+---------------+--------------------------------------------------+ | **Clang / LLVM** | 14+ | Required by ``bindgen`` for FFI generation | +------------------+---------------+--------------------------------------------------+ | **Git** | 2.30+ | Submodule management | +------------------+---------------+--------------------------------------------------+ | **task** (opt) | 3.x | Local task runner (``Taskfile.yaml``) | +------------------+---------------+--------------------------------------------------+ | **Android NDK** | r25+ | Cross-compile for Android (optional on macOS) | | (optional) | | | +------------------+---------------+--------------------------------------------------+ Installing Dependencies ----------------------- macOS (Homebrew) ~~~~~~~~~~~~~~~~ .. code-block:: shell # Rust (via rustup — manages toolchains automatically) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" # CMake and LLVM (clang for bindgen) brew install cmake llvm # Task runner (optional — for Taskfile.yaml) brew install go-task # Xcode Command Line Tools (required for iOS/macOS targets) xcode-select --install Linux (apt) ~~~~~~~~~~~ .. code-block:: shell curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" sudo apt update && sudo apt install -y cmake clang libclang-dev git # Task runner (optional) sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin Windows ~~~~~~~ .. code-block:: shell # Install rustup from https://rustup.rs # Install CMake from https://cmake.org/download/ (add to PATH) # Install LLVM/Clang from https://releases.llvm.org/ (add to PATH) # Install Visual Studio Build Tools (C++ workload) Android NDK (all platforms, optional) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Required only for ``aarch64-linux-android`` / ``x86_64-linux-android`` targets. .. code-block:: shell # Via Android Studio SDK Manager, or: sdkmanager --install "ndk;28.2.13676358" # Set environment variables (add to your shell profile): export ANDROID_NDK_HOME="$HOME/Library/Android/sdk/ndk/27.0.12077973" export PATH="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin:$PATH" # On Linux, replace darwin-x86_64 with linux-x86_64. ---- First-Time Setup ================ .. code-block:: shell # Clone the repository git clone ccc_rust && cd ccc_rust # Initialise the wolfSSL submodule (required — build fails without it) git submodule update --init --recursive # Verify the toolchain (rustup reads rust-toolchain.toml automatically) rustc --version # should print stable ≥ 1.85 cmake --version # should print ≥ 3.24 ---- Building ======== Native Build (Host Machine) ---------------------------- .. code-block:: shell cargo build --workspace # debug cargo build --workspace --release # release (optimised) Cross-Compile Targets --------------------- Cargo aliases are defined in ``.cargo/config.toml``: .. code-block:: shell # Apple cargo build-ios # aarch64-apple-ios cargo build-ios-sim # aarch64-apple-ios-sim cargo build-macos-arm64 # aarch64-apple-darwin cargo build-macos-x64 # x86_64-apple-darwin cargo build-all-apple # all three Apple targets at once # Android (requires NDK — see above) cargo build-android-arm64 # aarch64-linux-android cargo build-android-x64 # x86_64-linux-android # Release variants: append --release cargo build-ios --release cargo build-macos-arm64 --release wolfSSL Build Overrides ~~~~~~~~~~~~~~~~~~~~~~~~ The ``build.rs`` script accepts two environment variables: ``WOLFSSL_SOURCE_DIR`` Override the wolfSSL source path (default: ``vendors/wolfssl``). Useful in CI when the submodule is at a non-standard location. ``WOLFSSL_INSTALL_DIR`` Point to a pre-installed wolfSSL (must contain ``include/wolfssl/`` and ``lib/libwolfssl.a``). Skips the CMake build entirely. Stub FFI (no C build) ~~~~~~~~~~~~~~~~~~~~~~ For type-checking without building wolfSSL (CI lint jobs, docs): .. code-block:: shell cargo check -p ccc-crypto-wolfssl --features stub_ffi ---- Testing ======= .. code-block:: shell # Unit tests (all crates) cargo test --workspace # Conformance test binary (NIST / RFC vectors) cargo run -p ccc-conformance-tests # Run a single test by name cargo test --workspace test_name # Clippy (lint — treat warnings as errors) cargo clippy --workspace -- -D warnings # Format check cargo fmt --check ---- Build Artifacts =============== All output lands under ``target/``. The directory structure is: :: target/ ├── debug/ ← native host debug │ ├── conformance ← conformance test binary │ ├── libccc_crypto_core.rlib ← core crate (Rust lib) │ ├── libccc_crypto_wolfssl.rlib ← wolfSSL provider (Rust lib) │ └── build/ccc-crypto-wolfssl-*/out/ │ ├── lib/libwolfssl.a ← wolfSSL static library │ └── include/wolfssl/ ← generated wolfSSL headers ├── release/ ← native host release │ └── (same layout as debug/) ├── aarch64-apple-ios/ │ └── debug/ | release/ ← iOS artifacts ├── aarch64-apple-darwin/ │ └── debug/ | release/ ← macOS ARM64 artifacts ├── x86_64-apple-darwin/ │ └── debug/ | release/ ← macOS x86_64 artifacts ├── aarch64-linux-android/ │ └── debug/ | release/ ← Android ARM64 artifacts └── x86_64-linux-android/ └── debug/ | release/ ← Android x86_64 artifacts Key Artifacts per Target ~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------+--------------------------------------------------------------+ | Artifact | Path | +=================================+==============================================================+ | Core Rust library | ``target///libccc_crypto_core.rlib`` | +---------------------------------+--------------------------------------------------------------+ | wolfSSL provider library | ``target///libccc_crypto_wolfssl.rlib`` | +---------------------------------+--------------------------------------------------------------+ | wolfSSL static C library | ``target///build/ccc-crypto-wolfssl-*/out/`` | | | ``lib/libwolfssl.a`` | +---------------------------------+--------------------------------------------------------------+ | Conformance test binary | ``target///conformance`` | +---------------------------------+--------------------------------------------------------------+ Where ```` is the Rust target triple (e.g. ``aarch64-apple-ios``) and ```` is ``debug`` or ``release``. .. note:: These crates produce **rlib** (Rust library) output. The Milestone 2 bridge crate (in the separate ``ccc_cryptography`` repository) adds ``crate-type = ["cdylib", "staticlib"]`` to produce the ``.so`` / ``.dylib`` / ``.a`` artifacts consumed by Flutter. ---- Publish ======= The Rust crypto library remains a pure Rust crate with no Flutter or FFI-specific code. Option 1 -------- Option 1: Build from source via Cargokit (recommended for development) * Cargokit compiles the Rust code at build time for each platform * No precompiled binaries are needed Option 2 -------- Option 2: Cargokit precompiled binaries via GitHub Releases (recommended for pub.dev) * The Rust crate is compiled into platform-specific binaries (staticlib for iOS/macOS, cdylib for Android) * Binaries are uploaded to GitHub Releases * Cargokit fetches the correct binary at build time based on the target platform * This allows pub.dev users to get native performance without needing Rust or a build environment Workflow ~~~~~~~~ * CI builds the Rust crate for all 5 platform targets * CI uploads the .so/.dylib/.dll/.framework to a GitHub Release tagged with the Cargo package hash * When consumers run flutter build, Cargokit downloads the precompiled binary instead of compiling * If no precompiled binary exists, it falls back to source build * Pros: Fast builds for consumers, no Rust toolchain needed, no repo bloat, built into FRB, single repo * Cons: Requires CI pipeline to build + upload binaries * Best for: pub.dev releases, distributing to teams without Rust installed ---- Workspace Layout ================ :: ccc_rust/ ├── Cargo.toml workspace manifest ├── rust-toolchain.toml pinned stable toolchain + targets ├── Taskfile.yaml local task runner (task CLI) ├── ci.sh CI/CD build script ├── .cargo/config.toml cross-compile aliases + linker config ├── vendors/ │ ├── README.md submodule pin rationale │ └── wolfssl/ git submodule → wolfSSL v5.7.2-stable ├── crates/ │ ├── ccc-crypto-core/ shared traits, enums, registry │ └── ccc-crypto-wolfssl/ wolfSSL/wolfCrypt provider ├── tests/ │ └── conformance/ NIST/RFC conformance test binary └── docs/ architecture + design documents ---- Troubleshooting =============== wolfSSL source not found ~~~~~~~~~~~~~~~~~~~~~~~~~ :: wolfSSL source not found at .../vendors/wolfssl. Run `git submodule update --init --recursive` to fetch it. The wolfSSL submodule was not initialised. Run the command shown in the error. Linker errors on Apple (undefined symbols) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ensure the ``-lc++`` link arg is set for Apple targets. This is configured in ``.cargo/config.toml`` and should work automatically. If you see linker errors about C++ symbols, verify Xcode Command Line Tools are installed: .. code-block:: shell xcode-select --install Android linker not found ~~~~~~~~~~~~~~~~~~~~~~~~~ :: linker `aarch64-linux-android21-clang` not found The Android NDK toolchain is not in your PATH. See the "Android NDK" section above. bindgen fails / libclang not found ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``bindgen`` needs ``libclang``. On macOS, install LLVM via Homebrew: .. code-block:: shell brew install llvm export LIBCLANG_PATH="$(brew --prefix llvm)/lib" On Linux: .. code-block:: shell sudo apt install libclang-dev ---- Plugin Integration Notes ========================= When building the Milestone 2 Flutter plugin (``ccc_cryptography``): 1. The bridge crate depends on these crates via git tag:: [dependencies] ccc-crypto-core = { git = "...", tag = "v0.1.0" } ccc-crypto-wolfssl = { git = "...", tag = "v0.1.0" } 2. The bridge crate sets ``crate-type = ["cdylib", "staticlib"]``. 3. Call ``ccc_crypto_wolfssl::init()`` from the bridge's ``ccc_init()``. 4. ``flutter_rust_bridge`` and all Dart/Flutter dependencies live exclusively in the plugin repo — never in this one.