CCC Flutter Plugin — Linux Build & Test Guide ============================================= :Created: 2026-03-16 :Status: Pending (Phase 4.4 and Phase 6.7) :Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.4, 6.7 :Platform: Linux — x86_64 (Ubuntu 22.04 LTS or later recommended) Overview -------- The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS, and Android. All 16 integration tests pass on those three platforms. Two Linux-specific tasks remain open in the Milestone 2 verification gate: * **Phase 4.4** — ``flutter build linux`` succeeds * **Phase 6.7** — all 16 integration tests pass on a Linux host This guide provides the step-by-step procedure for a developer on a Linux machine to complete those two tasks and tick off the remaining gate items. Related Documents ~~~~~~~~~~~~~~~~~ * ``docs/ccc_fplugin_phases.rst`` — master phase tracker (tasks 4.4, 6.7, and the Milestone 2 Verification Gate) * ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture * ``docs/ccc_fplugin_build_windows.rst`` — equivalent guide for Windows * ``docs/README_DEV.rst`` — FRB v2 + Cargokit background ---- Platform Status Summary ----------------------- ============================== ========= ==================== Platform Build Integration Tests ============================== ========= ==================== iOS (aarch64-apple-ios) ✅ 17.1 MB ✅ 16/16 passed Android (arm64, armv7, x86_64) ✅ 44.6 MB ✅ 16/16 passed macOS (aarch64-apple-darwin) ✅ 44.5 MB ✅ 16/16 passed **Linux (x86_64-linux-gnu)** **⏳ TBD** **⏳ TBD** Windows (x86_64-msvc) ⏳ deferred ⏳ deferred ============================== ========= ==================== ---- Prerequisites ------------- Install the following on the Linux host before proceeding. Commands shown assume **Ubuntu 22.04 LTS** (or Debian-compatible). Adjust package names for other distributions as needed. 1. System Build Tools ~~~~~~~~~~~~~~~~~~~~~ :: sudo apt update sudo apt install -y \ build-essential \ cmake \ ninja-build \ pkg-config \ libgtk-3-dev \ git \ curl \ unzip ``libgtk-3-dev`` is required by the Flutter Linux embedding. ``cmake`` must be ≥ 3.10 (``linux/CMakeLists.txt`` minimum requirement). Verify:: cmake --version # ≥ 3.10 2. Clang / libclang ~~~~~~~~~~~~~~~~~~~~ wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from C headers. ``bindgen`` requires ``libclang`` at build time. :: sudo apt install -y clang libclang-dev Verify:: clang --version llvm-config --version # optional, confirms LLVM installation On Ubuntu 22.04 the default APT package installs Clang 14 and places ``libclang.so`` in a path that ``bindgen`` finds automatically — no ``LIBCLANG_PATH`` override is required in the typical case. 3. Flutter SDK ~~~~~~~~~~~~~~ Follow the official Flutter Linux installation: https://docs.flutter.dev/get-started/install/linux After installation:: flutter doctor All items relevant to Linux desktop must be green. Enable Linux desktop if not already done:: flutter config --enable-linux-desktop 4. Rust Toolchain ~~~~~~~~~~~~~~~~~ Install ``rustup``:: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" Verify the stable toolchain is active:: rustup show Add the Linux target if not already present:: rustup target add x86_64-unknown-linux-gnu 5. SSH Access to the Internal Repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server. Ensure the SSH key for ``git@10.0.5.109`` is present and loaded:: ssh -T git@10.0.5.109 Confirm authentication succeeds before proceeding. ---- Rust Target Setup ----------------- Add the Linux GNU target to the active toolchain:: rustup target add x86_64-unknown-linux-gnu Verify it is listed:: rustup target list --installed Expected output includes ``x86_64-unknown-linux-gnu``. ---- Dependency Configuration ------------------------ The bridge crate at ``rust/Cargo.toml`` currently uses **local macOS path dependencies** that resolve to ``/Volumes/LUM/...``. These paths do not exist on a Linux machine and must be replaced before building. Two options are available: Option A — Local Clone (Development) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Clone ``lum_ccc_rust`` to a local path, then set path deps accordingly:: git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git ~/src/lum_ccc_rust Edit ``rust/Cargo.toml``:: ccc-crypto-core = { path = "/home//src/lum_ccc_rust/crates/ccc-crypto-core" } ccc-crypto-wolfssl = { path = "/home//src/lum_ccc_rust/crates/ccc-crypto-wolfssl" } Option B — Git/SSH Dependencies (Recommended) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Switch to the git/SSH dependencies that are already present (commented out) in ``rust/Cargo.toml``. **Remove** the local macOS path lines:: ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" } ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" } **Uncomment** the git lines:: ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" } ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" } Pre-fetch the dependency to confirm SSH access works:: cd rust cargo fetch .. note:: Before cutting the ``v0.1.0`` tag, replace the commit hash with the exact release tag — see the Milestone 2 Verification Gate in ``docs/ccc_fplugin_phases.rst``. ---- Environment Variables --------------------- Linux with the APT-installed ``clang`` + ``libclang-dev`` packages typically requires **no environment variable overrides** — bindgen locates ``libclang.so`` via ``llvm-config`` automatically. LIBCLANG_PATH (if needed) ~~~~~~~~~~~~~~~~~~~~~~~~~~ If the build fails with a bindgen error about ``libclang`` not found, set ``LIBCLANG_PATH`` explicitly:: export LIBCLANG_PATH=$(llvm-config --libdir) Add to ``~/.bashrc`` or ``~/.profile`` to make it permanent. To use ``.cargo/config.toml`` instead:: [env] LIBCLANG_PATH = "/usr/lib/llvm-14/lib" Verify the library is present:: ls $LIBCLANG_PATH/libclang.so* BINDGEN_EXTRA_CLANG_ARGS (if needed) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If bindgen cannot locate system headers (e.g. ``stddef.h`` errors), add:: export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu" This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android in Phase 4.6. On Ubuntu 22.04 with standard clang, this is not expected to be necessary. ---- Phase 4.4 — Build Verification ------------------------------- Run from the ``example/`` directory:: cd example flutter build linux --release Expected result: * Build completes with no errors. * The compiled binary and Cargokit-built ``.so`` are placed in:: example/build/linux/x64/release/bundle/ * Record the output bundle size for the verification gate entry. .. note:: Cargokit invokes ``cargo build --target x86_64-unknown-linux-gnu`` automatically during ``flutter build linux``. The first build compiles wolfSSL from source and may take several minutes. On success, update ``docs/ccc_fplugin_phases.rst`` task 4.4 to ✅ and record the build output bundle size. ---- Phase 6.7 — Integration Tests on Linux ---------------------------------------- Run from the ``example/`` directory:: cd example flutter test integration_test/ccc_crypto_test.dart -d linux Expected result: **16/16 tests passed**. The 16 tests and their coverage:: [5.1] AEAD roundtrip — AES-256-GCM encrypt/decrypt (1 KB) [5.2] AEAD roundtrip — ChaCha20-Poly1305 encrypt/decrypt (1 KB) [5.3] AEAD tamper — modified ciphertext → CccAuthenticationFailed [5.4] KDF known-vector — HKDF-SHA256 vs RFC 5869 Test Case 1 (42 bytes) [5.5] MAC roundtrip — HMAC-SHA256 compute + verify returns true [5.6] MAC tamper — modified data → verify returns false [5.7] Hash known-vector — SHA-256/384/512 ("abc" test vector) [5.8] KEM roundtrip — X25519 keygen/encap/decap; shared secrets match [5.9] KEM roundtrip — X448 keygen/encap/decap; shared secrets match [5.10] Provider catalog — listProviders() non-empty; getCapabilities() returns scores [5.11] Self-test — runSelfTest() returns structured report [5.12] Error handling — invalid key/nonce lengths → correct CccException subtypes [5.13] Algorithm ID mapping — catalog IDs match Rust enum discriminants (AES-GCM=12, ...) .. note:: Test 5.11 (self-test) is expected to report AEAD length-mismatch failures for AES-256-GCM and ChaCha20-Poly1305. This is a known upstream bug in ``ccc_rust`` (the self-test vectors do not account for the appended auth tag in encrypt output). It is not Linux-specific and the test still passes overall. See Phase 5 known issues in ``docs/ccc_fplugin_phases.rst``. On success, update ``docs/ccc_fplugin_phases.rst`` task 6.7 to ✅ and mark the corresponding Milestone 2 Verification Gate item. ---- Linux Verification Checklist ----------------------------- Complete this checklist on the Linux host. Items map directly to the open entries in the Milestone 2 Verification Gate in ``docs/ccc_fplugin_phases.rst``. .. list-table:: :header-rows: 1 :widths: 5 80 15 * - # - Item - Status * - L-1 - ``rustup target add x86_64-unknown-linux-gnu`` installed and listed - ☐ * - L-2 - ``rust/Cargo.toml`` updated — local macOS paths replaced with git/SSH deps (or Linux local paths) - ☐ * - L-3 - ``clang`` and ``libclang-dev`` installed; bindgen resolves ``libclang.so`` without manual override - ☐ * - L-4 - ``ssh -T git@10.0.5.109`` succeeds (SSH key loaded) - ☐ * - L-5 - ``flutter build linux --release`` succeeds; bundle size recorded - ☐ * - L-6 - Native ``.so`` present in the release bundle directory - ☐ * - L-7 - ``flutter test integration_test/ccc_crypto_test.dart -d linux`` — 16/16 passed - ☐ * - L-8 - Tasks 4.4 and 6.7 marked ✅ in ``docs/ccc_fplugin_phases.rst`` - ☐ * - L-9 - Milestone 2 Verification Gate Linux items checked - ☐ ---- Troubleshooting --------------- bindgen / libclang not found ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom**:: error: failed to run custom build command for `ccc-crypto-wolfssl` thread 'main' panicked at '... Unable to find libclang ...' **Fix:** Install ``clang`` and ``libclang-dev``:: sudo apt install -y clang libclang-dev Then set ``LIBCLANG_PATH`` if bindgen still cannot find it:: export LIBCLANG_PATH=$(llvm-config --libdir) If multiple LLVM versions are installed, specify the one in use:: export LIBCLANG_PATH=/usr/lib/llvm-14/lib Missing system headers during bindgen ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``, or similar C standard headers. **Fix:** Install the Linux headers package:: sudo apt install -y linux-libc-dev If the error persists, set:: export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu" GTK development headers not found ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** ``flutter build linux`` fails with errors about missing ``gtk/gtk.h`` or ``pkg-config`` not finding ``gtk+-3.0``. **Fix:**:: sudo apt install -y libgtk-3-dev pkg-config cmake not found or too old ~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** Cargokit or ``flutter build linux`` fails with "CMake not found" or "CMake version 3.10 or later required". **Fix:**:: sudo apt install -y cmake Ubuntu 22.04 ships CMake 3.22 which satisfies the ≥ 3.10 requirement. If on an older distro, install via the Kitware APT repository or snap:: sudo snap install cmake --classic cargo fetch fails — SSH key not found ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom**:: error: failed to authenticate when downloading repository Caused by: ... no auth methods succeeded **Fix:** Ensure the SSH agent has the correct key loaded:: eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519 # adjust key filename Or configure ``~/.ssh/config``:: Host 10.0.5.109 User git IdentityFile ~/.ssh/id_ed25519 flutter build linux fails — display not found ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** Running integration tests on a headless server fails with a display-related error (Flutter Linux requires a display server). **Fix:** Use a virtual framebuffer:: sudo apt install -y xvfb Xvfb :99 -screen 0 1280x1024x24 & export DISPLAY=:99 flutter test integration_test/ccc_crypto_test.dart -d linux Alternatively, run on a machine with a desktop environment, or use a remote desktop session. ninja not found ~~~~~~~~~~~~~~~~ **Symptom:** CMake generates a build but ``ninja`` is not found. **Fix:**:: sudo apt install -y ninja-build ---- After Completion ---------------- Once both Phase 4.4 and Phase 6.7 are verified: 1. Update ``docs/ccc_fplugin_phases.rst``: * Mark tasks 4.4 and 6.7 ✅ * Check the corresponding Milestone 2 Verification Gate entries 2. If the ``ccc_rust`` dependency commit hash is still floating, pin it to the final ``v0.1.0`` tag of that repository. 3. Proceed with the remaining Phase 6 tasks (6.9 example app update, 6.10 CHANGELOG, 6.11 final review, 6.12 ``v0.1.0`` tag). Windows (Phase 4.5 / Phase 6.8) follows the same general pattern but substitutes ``x86_64-pc-windows-msvc`` as the Rust target. LLVM must be installed manually on Windows, and ``LIBCLANG_PATH`` is always required. See ``docs/ccc_fplugin_build_windows.rst`` for full details.