lum_ccc_fplugin/docs/ccc_fplugin_build_linux.rst

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/<user>/src/lum_ccc_rust/crates/ccc-crypto-core" }
  ccc-crypto-wolfssl = { path = "/home/<user>/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.