Installation

This guide covers installing Circuit for different platforms and use cases.

Rust Development

Prerequisites

  • Rust 1.70 or later
  • Cargo (comes with Rust)

Install Rust

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

Verify installation:

rustc --version
cargo --version

Using mise (optional/recommended)

If you prefer to use mise for developer tool/version management, you can use the repo-provided mise.toml and the rust-toolchain file to automatically install and pin the correct Rust version and components.

# Install mise (only if you don't have it)
curl https://mise.run | sh

# Activate mise in your shell (zsh example)
eval "$(~/.local/bin/mise activate zsh)"

# From the repository root, activate the Rust toolchain and install configured tools
cd circuit
mise use rust@1.90.0
mise install

# Verify cargo/rust version (runs inside mise environment)
mise x -- cargo --version

Note: .rust-toolchain.toml is also included and will ensure rustup uses the right channel and components if you're using rustup directly.

Clone Circuit

git clone https://github.com/blankly-app/circuit.git
cd circuit

Build All Packages

# Build all packages in release mode
cargo build --release

# Run tests to verify everything works
cargo test

# Run an example
cargo run --example calculator

Platform-Specific Installation

iOS/macOS (Swift)

Install Additional Targets

# For iOS devices (ARM64)
rustup target add aarch64-apple-ios

# For iOS Simulator (x86_64)
rustup target add x86_64-apple-ios

# For iOS Simulator (ARM64, M1/M2 Macs)
rustup target add aarch64-apple-ios-sim

# For macOS
rustup target add aarch64-apple-darwin  # Apple Silicon
rustup target add x86_64-apple-darwin   # Intel Macs

Build for iOS

# Build the FFI library for iOS
cargo build --release --target aarch64-apple-ios -p circuit-ffi

# The library will be at: target/aarch64-apple-ios/release/libcircuit_ffi.a

See the Swift Integration Guide for detailed Xcode setup.

Android (Kotlin)

Install NDK and Targets

  1. Install Android NDK via Android Studio or standalone

  2. Add Rust targets:

rustup target add aarch64-linux-android   # ARM64
rustup target add armv7-linux-androideabi # ARMv7
rustup target add i686-linux-android      # x86
rustup target add x86_64-linux-android    # x86_64

Configure Cargo for Android

Create or edit ~/.cargo/config.toml:

[target.aarch64-linux-android]
ar = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
linker = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android30-clang"

[target.armv7-linux-androideabi]
ar = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
linker = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi30-clang"

Replace /path/to/ndk with your NDK installation path.

Build for Android

# Build for ARM64 (most common)
cargo build --release --target aarch64-linux-android -p circuit-ffi

# The library will be at: target/aarch64-linux-android/release/libcircuit_ffi.so

See the Kotlin Integration Guide for Android Studio setup.

Web/React (WebAssembly)

Install wasm-pack

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Or with cargo:

cargo install wasm-pack

Build WASM Package

cd circuit-wasm
wasm-pack build --target web --release

# Or for bundlers (webpack, vite, etc.)
wasm-pack build --target bundler --release

This creates a pkg/ directory with:

  • circuit_wasm_bg.wasm - The WebAssembly module
  • circuit_wasm.js - JavaScript bindings
  • circuit_wasm.d.ts - TypeScript definitions
  • package.json - NPM package manifest

Install in Your Web Project

cd your-web-project
npm install ../circuit/circuit-wasm/pkg

Or publish to NPM and install normally.

See the React Integration Guide for detailed web setup.

Development Tools

Optional: Install cargo-watch for Auto-rebuild

cargo install cargo-watch

Use it during development:

cargo watch -x test
cargo watch -x 'run --example calculator'

Optional: Install cargo-expand for Macro Debugging

cargo install cargo-expand

Useful for inspecting generated code:

cargo expand -p circuit-core

Optional: Install mdBook for Documentation

cargo install mdbook

Build and serve the documentation locally:

cd docs
mdbook serve --open

Verification

Run All Tests

cargo test --all

Build All Targets

# Native
cargo build --release

# iOS
cargo build --release --target aarch64-apple-ios -p circuit-ffi

# Android
cargo build --release --target aarch64-linux-android -p circuit-ffi

# WASM
cd circuit-wasm && wasm-pack build --target web

Run Examples

cargo run --example calculator

Troubleshooting

Linker Errors on macOS

If you encounter linker errors, ensure you have Xcode command line tools:

xcode-select --install

Android NDK Not Found

Ensure ANDROID_NDK_HOME is set:

export ANDROID_NDK_HOME=/path/to/android-ndk

Add to your .bashrc or .zshrc for persistence.

WASM Build Fails

Ensure you have the wasm32 target:

rustup target add wasm32-unknown-unknown

And install wasm-bindgen-cli:

cargo install wasm-bindgen-cli

Next Steps