lum_ccc_fplugin/docs/ccc_fplugin_build_windows.rst

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_<target>`` 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.