Skip to main content

Building from Source

This guide covers building FIDO Bridge from source for development purposes.

Development Environment Setup​

Prerequisites​

System Requirements​

  • OS: Linux (Ubuntu 22.04+, Fedora 38+, Arch Linux)
  • RAM: 4GB minimum, 8GB recommended
  • Disk: 5GB free space for build artifacts

Required Tools​

  1. Rust Toolchain (1.90+):

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source $HOME/.cargo/env
    rustc --version  # Verify installation

  2. Git:

    sudo apt install git  # Debian/Ubuntu
    sudo dnf install git  # Fedora

  3. Build Tools:

    # Debian/Ubuntu
    sudo apt install build-essential pkg-config libssl-dev

    # Fedora
    sudo dnf install gcc pkg-config openssl-devel

    # Arch Linux
    sudo pacman -S base-devel openssl

  4. Flutter SDK (3.0+):

    # Install via snap (recommended on Ubuntu)
    sudo snap install flutter --classic

    # Or download from https://flutter.dev/docs/get-started/install
    flutter doctor  # Check for issues

  5. Android SDK:

    # Install Android Studio from https://developer.android.com/studio
    # Or use command-line tools
    flutter doctor --android-licenses  # Accept licenses

  6. Java Development Kit (JDK 11+):

    sudo apt install openjdk-17-jdk  # Debian/Ubuntu
    sudo dnf install java-17-openjdk  # Fedora

Optional Tools​

  • Rust Analyzer (IDE support):

    rustup component add rust-analyzer

  • Clippy (linter):

    rustup component add clippy

  • rustfmt (formatter):

    rustup component add rustfmt

Clone the Repository​

git clone https://github.com/0xC9C3/fido-bridge.git
cd fido-bridge

Building Rust Components​

The Rust workspace contains three crates:

  • client: Linux UHID FIDO client
  • server: Relay server
  • transport: Shared library (crypto, protocol)

Build All Crates​

# Debug build (faster compilation, slower runtime)
cargo build

# Release build (optimized for performance)
cargo build --release

Binaries will be at:

  • target/debug/client (or target/release/client)
  • target/debug/server (or target/release/server)

Build Individual Crates​

# Build only the client
cargo build --release -p client

# Build only the server
cargo build --release -p server

# Build transport library (dependency for client/server)
cargo build --release -p transport

Development Build (with Debug Symbols)​

# Debug build with full symbols
RUST_BACKTRACE=1 cargo build

# Run with debug logging
RUST_LOG=debug ./target/debug/client

Check for Issues Without Building​

cargo check  # Fast syntax/type checking
cargo clippy  # Lint for common mistakes

Building the Android App​

cd app

Install Dependencies​

flutter pub get

Build for Android​

Debug Build (for Testing)​

flutter build apk --debug

Output: app/build/app/outputs/flutter-apk/app-debug.apk

Release Build (for Production)​

flutter build apk --release

Output: app/build/app/outputs/flutter-apk/app-release.apk

Build for Specific ABI​

# ARM64 only (most modern devices)
flutter build apk --release --target-platform android-arm64

# ARMv7 (older 32-bit devices)
flutter build apk --release --target-platform android-arm

# x86_64 (emulator)
flutter build apk --release --target-platform android-x64

App Bundle (for Google Play)​

flutter build appbundle --release

Output: app/build/app/outputs/bundle/release/app-release.aab

Flutter Rust Bridge Code Generation​

The app uses Flutter Rust Bridge (FRB) to call Rust code from Dart.

Regenerate Bindings:

cd app
flutter_rust_bridge_codegen \
  --rust-input ../crates/transport/src/api.rs \
  --dart-output lib/rust/api/simple.dart

When to Regenerate:

  • After modifying Rust API in /crates/transport/src/api.rs
  • After updating flutter_rust_bridge dependency version

Hot Reload During Development​

# Connect Android device or start emulator
flutter devices

# Run in debug mode with hot reload
flutter run

Hot Reload: Press r in terminal to reload code changes without restarting app.

Hot Restart: Press R to fully restart app.

Building the Documentation​

Install Node.js and npm​

# Debian/Ubuntu
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

# Verify
node --version  # Should be 18+
npm --version

Install Docusaurus Dependencies​

cd docs
npm install

Local Development Server​

npm start

Visit: http://localhost:3000

Changes to Markdown files will hot-reload automatically.

Build Static Site​

npm run build

Output: docs/build/ (static HTML/CSS/JS)

Serve Built Site Locally​

npm run serve

Visit: http://localhost:3000

Project Structure​

fido-bridge/
├── crates/
│   ├── client/          # Linux UHID FIDO client
│   │   ├── src/
│   │   │   ├── main.rs              # Entry point
│   │   │   ├── uhid_fido.rs         # UHID device management
│   │   │   ├── webauthn_handler.rs  # WebAuthn message handling
│   │   │   ├── message_handler.rs   # Message routing
│   │   │   ├── storage.rs           # Persistent storage
│   │   │   └── uhid.rs              # UHID kernel interface
│   │   ├── tests/                   # Integration tests
│   │   └── Cargo.toml
│   ├── server/          # Relay server
│   │   ├── src/
│   │   │   ├── main.rs              # Axum server
│   │   │   ├── blob.rs              # Message storage
│   │   │   └── handlers.rs          # HTTP handlers
│   │   └── Cargo.toml
│   └── transport/       # Shared library
│       ├── src/
│       │   ├── pairing/             # Pairing protocol
│       │   │   ├── mod.rs
│       │   │   ├── protocol.rs      # SPAKE2 flow
│       │   │   └── crypto.rs        # Cryptographic primitives
│       │   ├── secure_channel.rs    # X25519 ECDH + AES-GCM
│       │   ├── webauthn_messages.rs # CTAP2 messages
│       │   ├── transaction.rs       # Transaction state
│       │   └── client.rs            # HTTP client
│       └── Cargo.toml
├── app/                 # Flutter Android app
│   ├── lib/
│   │   ├── main.dart                # App entry point
│   │   ├── src/
│   │   │   ├── screens/             # UI screens
│   │   │   ├── services/            # Business logic
│   │   │   ├── providers/           # State management
│   │   │   └── models/              # Data models
│   │   └── rust/                    # Flutter Rust Bridge bindings
│   ├── android/
│   │   └── app/src/main/kotlin/     # Kotlin NFC handler
│   ├── pubspec.yaml                 # Flutter dependencies
│   └── Cargo.toml                   # Rust dependencies for app
├── docs/                # Docusaurus documentation
│   ├── docs/                        # Markdown content
│   ├── docusaurus.config.js         # Site configuration
│   ├── sidebars.js                  # Navigation
│   └── package.json                 # npm dependencies
├── Cargo.toml           # Workspace manifest
└── README.md

Build Configurations​

Rust Build Profiles​

Debug (default):

[profile.dev]
opt-level = 0        # No optimization
debug = true         # Full debug symbols

Release:

[profile.release]
opt-level = 3        # Maximum optimization
debug = false        # No debug symbols
lto = true           # Link-time optimization
codegen-units = 1    # Better optimization, slower build

Custom (in Cargo.toml):

[profile.dev-optimized]
inherits = "dev"
opt-level = 2        # Some optimization, faster runtime than dev

Use: cargo build --profile dev-optimized

Flutter Build Flavors​

Define flavors for different environments (future enhancement):

# Development flavor
flutter build apk --debug --flavor dev

# Production flavor
flutter build apk --release --flavor prod

Cross-Compilation​

Build for Different Architectures​

ARM64:

rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

ARMv7 (e.g., Raspberry Pi):

rustup target add armv7-unknown-linux-gnueabihf
cargo build --release --target armv7-unknown-linux-gnueabihf

Android Cross-Compilation​

Handled automatically by Flutter/Gradle for the app.

For standalone Rust on Android:

rustup target add aarch64-linux-android
cargo build --release --target aarch64-linux-android

Cleaning Build Artifacts​

Rust​

cargo clean  # Remove all build artifacts

Flutter​

cd app
flutter clean  # Remove Flutter build artifacts

Documentation​

cd docs
rm -rf build .docusaurus  # Remove Docusaurus cache and build

Complete Clean​

# From project root
cargo clean
cd app && flutter clean && cd ..
cd docs && rm -rf build .docusaurus node_modules && cd ..

Build Troubleshooting​

"linker cc not found"​

Solution: Install build tools

sudo apt install build-essential  # Debian/Ubuntu

"Could not find openssl"​

Solution: Install OpenSSL development files

sudo apt install libssl-dev  # Debian/Ubuntu
sudo dnf install openssl-devel  # Fedora

Flutter "Android SDK not found"​

Solution:

flutter doctor --android-licenses
flutter config --android-sdk /path/to/android-sdk

"Rust Compiler Version Mismatch"​

Solution: Update Rust

rustup update stable

Out of Memory During Rust Build​

Solution: Reduce parallel jobs

cargo build --release -j2  # Use only 2 parallel jobs

Or increase swap space:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Continuous Integration​

FIDO Bridge uses GitHub Actions for CI (see .github/workflows/).

Workflows:

  • rust.yml: Build and test Rust code
  • flutter.yml: Build and test Android app
  • docs.yml: Build and deploy documentation

Run CI Locally (optional):

# Install act (GitHub Actions local runner)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Run workflows locally
act push  # Simulate push event

Next Steps​