CCC Flutter Plugin — Windows Build & Test Guide =============================================== :Created: 2026-03-16 :Status: Pending (Phase 4.5 and Phase 6.8) :Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.5, 6.8 :Platform: Windows 10 / Windows 11 — x86_64 Overview -------- The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS, and Android. All 16 integration tests pass on those three platforms. Two Windows-specific tasks remain open in the Milestone 2 verification gate: * **Phase 4.5** — ``flutter build windows`` succeeds * **Phase 6.8** — all 16 integration tests pass on a Windows host This guide provides the step-by-step procedure for a developer on a Windows 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.5, 6.8, and the Milestone 2 Verification Gate) * ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture * ``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) ⏳ deferred ⏳ deferred **Windows (x86_64-msvc)** **⏳ TBD** **⏳ TBD** ============================== ========= ==================== ---- Prerequisites ------------- Install the following on the Windows host before proceeding. 1. Visual Studio 2022 ~~~~~~~~~~~~~~~~~~~~~ Install **Visual Studio 2022** (Community edition or higher) with the following workloads and components: * **Desktop development with C++** * MSVC v143 — VS 2022 C++ x64/x86 build tools (selected by default) * Windows 11 SDK (10.0.22000 or later) — or Windows 10 SDK ≥ 10.0.20348 * CMake tools for Windows (or install CMake ≥ 3.14 separately) .. note:: ``windows/CMakeLists.txt`` requires ``cmake_minimum_required(VERSION 3.14)``. The CMake bundled with VS 2022 satisfies this requirement. 2. Flutter SDK ~~~~~~~~~~~~~~ Install Flutter (stable channel) and verify:: flutter doctor All items relevant to Windows desktop must be green. Enable Windows desktop if not already done:: flutter config --enable-windows-desktop 3. Rust Toolchain (MSVC ABI — not GNU) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Install ``rustup`` from https://rustup.rs. During installation select the **MSVC** ABI, which is the default when Visual Studio is detected. .. warning:: The GNU ABI toolchain (``*-pc-windows-gnu``) does **not** link against the MSVC C runtime and will fail when building wolfSSL. Only ``x86_64-pc-windows-msvc`` is supported. Verify the active toolchain is MSVC:: rustup show Add the Windows target if not already present:: rustup target add x86_64-pc-windows-msvc 4. LLVM / Clang ~~~~~~~~~~~~~~~ wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from C headers. ``bindgen`` requires a Clang/libclang installation at build time. Install LLVM (≥ 14) using one of the following methods: * **winget** (preferred):: winget install LLVM.LLVM * **Chocolatey**:: choco install llvm * **Installer** from https://llvm.org/releases — check "Add LLVM to the system PATH" during install. After installation, set ``LIBCLANG_PATH`` (see § Environment Variables). 5. Git with SSH Access to the Internal Repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server. Ensure Git is installed and the SSH key for ``git@10.0.5.109`` is present:: ssh -T git@10.0.5.109 Confirm authentication succeeds before proceeding. ---- Rust Target Setup ----------------- Add the Windows MSVC target to the active toolchain:: rustup target add x86_64-pc-windows-msvc Verify it is listed:: rustup target list --installed Expected output includes ``x86_64-pc-windows-msvc``. ---- 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 Windows machine and must be replaced before building. Two options are available: Option A — Local Clone (Development) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Clone ``lum_ccc_rust`` to a Windows path, then set path deps accordingly:: git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git C:\src\lum_ccc_rust Edit ``rust/Cargo.toml``:: ccc-crypto-core = { path = "C:/src/lum_ccc_rust/crates/ccc-crypto-core" } ccc-crypto-wolfssl = { path = "C:/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 --------------------- Set the following before running the build. Use PowerShell or set them permanently in System Properties → Advanced → Environment Variables. LIBCLANG_PATH ~~~~~~~~~~~~~ Required by ``bindgen`` (used in wolfSSL's ``build.rs``) to locate ``libclang.dll``. PowerShell:: $env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin" CMD:: set LIBCLANG_PATH=C:\Program Files\LLVM\bin Verify ``libclang.dll`` is present:: dir "$env:LIBCLANG_PATH\libclang.dll" Optionally, make it permanent via ``.cargo/config.toml`` in the project root:: [env] LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin" BINDGEN_EXTRA_CLANG_ARGS (if needed) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On Android, wolfSSL's ``build.rs`` required extra Clang arguments to find system headers; that fix was applied in Phase 4.6 via ``BINDGEN_EXTRA_CLANG_ARGS_`` in Cargokit's Android environment. A similar issue may occur on Windows if bindgen cannot locate MSVC headers. If the build fails with errors about missing ``stddef.h`` or similar standard headers, add:: $env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility" See the Troubleshooting section for full details. ---- Phase 4.5 — Build Verification ------------------------------- Run from the ``example/`` directory:: cd example flutter build windows --release Expected result: * Build completes with no errors. * The compiled ``.exe`` and the Cargokit-built ``.dll`` are placed in:: example\build\windows\x64\runner\Release\ * Record the output directory size for the verification gate entry. .. note:: Cargokit invokes ``cargo build --target x86_64-pc-windows-msvc`` automatically during ``flutter build windows``. The first build compiles wolfSSL from source and may take several minutes. On success, update ``docs/ccc_fplugin_phases.rst`` task 4.5 to ✅ and record the build output size. ---- Phase 6.8 — Integration Tests on Windows ----------------------------------------- Run from the ``example/`` directory:: cd example flutter test integration_test/ccc_crypto_test.dart -d windows 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 Windows-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.8 to ✅ and mark the corresponding Milestone 2 Verification Gate item. ---- Windows Verification Checklist ------------------------------- Complete this checklist on the Windows 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 * - W-1 - ``rustup target add x86_64-pc-windows-msvc`` installed and listed - ☐ * - W-2 - ``rust/Cargo.toml`` updated — local macOS paths replaced with git/SSH deps (or Windows local paths) - ☐ * - W-3 - ``LIBCLANG_PATH`` set and ``libclang.dll`` reachable at that path - ☐ * - W-4 - ``SSH -T git@10.0.5.109`` succeeds (SSH key loaded) - ☐ * - W-5 - ``flutter build windows --release`` succeeds; output size recorded - ☐ * - W-6 - Native ``.dll`` present and bundled in the release output directory - ☐ * - W-7 - ``flutter test integration_test/ccc_crypto_test.dart -d windows`` — 16/16 passed - ☐ * - W-8 - Tasks 4.5 and 6.8 marked ✅ in ``docs/ccc_fplugin_phases.rst`` - ☐ * - W-9 - Milestone 2 Verification Gate Windows 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:** Set ``LIBCLANG_PATH`` to the LLVM ``bin/`` directory containing ``libclang.dll``. Typical path after winget install:: C:\Program Files\LLVM\bin MSVC headers not found during bindgen ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``, or similar MSVC standard headers during the wolfSSL ``build.rs`` run. **Fix:** Ensure the MSVC C++ workload is installed in VS 2022, then add:: $env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility" This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android in Phase 4.6. If the issue persists, check that the VS 2022 "Windows SDK" component is installed (bindgen needs its ``include/`` headers). GNU toolchain conflict ~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** Linker errors referencing ``libgcc``, ``mingw``, or ``crt2.obj`` symbols. **Fix:** Confirm the active Rust toolchain is MSVC:: rustup show If the default is ``stable-x86_64-pc-windows-gnu``, override it for this project:: rustup override set stable-x86_64-pc-windows-msvc CMake not found ~~~~~~~~~~~~~~~ **Symptom:** Cargokit or ``flutter build windows`` fails reporting "CMake not found" or similar. **Fix:** Ensure CMake is in ``PATH``. VS 2022 installs CMake to:: C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin Add it to ``PATH``, or install the standalone CMake distribution and check "Add CMake to PATH" during setup. Verify:: cmake --version Windows long path errors ~~~~~~~~~~~~~~~~~~~~~~~~ wolfSSL's source tree and Cargo's registry can produce paths exceeding Windows' 260-character default limit. **Fix:** Enable long path support (requires an elevated PowerShell):: New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" ` -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force And configure Git:: git config --global core.longpaths true 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:: ssh-add $env:USERPROFILE\.ssh\id_ed25519 # adjust key filename Or configure ``~/.ssh/config``:: Host 10.0.5.109 User git IdentityFile ~/.ssh/id_ed25519 flutter build windows fails — missing flutter_windows.dll ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Symptom:** The built executable fails to run (not a build error). **Fix:** Always use ``flutter build windows --release`` for testing; never copy just the ``.exe``. The ``Release\`` folder must be kept intact — it contains ``flutter_windows.dll`` and ``data/``. ---- After Completion ---------------- Once both Phase 4.5 and Phase 6.8 are verified: 1. Update ``docs/ccc_fplugin_phases.rst``: * Mark tasks 4.5 and 6.8 ✅ * 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). Linux (Phase 4.4 / Phase 6.7) follows the same general pattern as Windows but substitutes ``x86_64-unknown-linux-gnu`` as the Rust target and uses a Clang package from the system package manager (e.g., ``apt install clang``). No ``LIBCLANG_PATH`` override is typically needed on Linux.