> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt > Use this file to discover all available pages before exploring further. # Building from Source > Complete guide to building IronClaw from source code ## Prerequisites Before building IronClaw, ensure you have the following installed: ### Required * **Rust 1.85+**: Install via [rustup](https://rustup.rs) ```bash theme={null} curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` * **WASM target**: Required for building bundled channels ```bash theme={null} rustup target add wasm32-wasip2 ``` * **wasm-tools**: Required for WASM component model ```bash theme={null} cargo install wasm-tools --locked ``` ### Database Options Choose one or both: #### PostgreSQL (Recommended for Production) * **PostgreSQL 15+** with pgvector extension ```bash theme={null} # macOS brew install postgresql@15 pgvector # Ubuntu/Debian sudo apt-get install postgresql-15 postgresql-15-pgvector # Create database createdb ironclaw # Enable pgvector psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;" ``` #### libSQL (For Development) * No installation needed - embedded database included * Perfect for development and testing * Zero-dependency local mode ## Quick Setup The fastest way to get started: ```bash theme={null} # Clone the repository git clone https://github.com/nearai/ironclaw.git cd ironclaw # Run developer setup script ./scripts/dev-setup.sh ``` This script: 1. Verifies rustup installation 2. Adds the `wasm32-wasip2` target 3. Installs `wasm-tools` 4. Runs `cargo check` to verify compilation 5. Runs tests using libSQL (no external database needed) ## Manual Build Process ### 1. Clone the Repository ```bash theme={null} git clone https://github.com/nearai/ironclaw.git cd ironclaw ``` ### 2. Development Build Build with default features (PostgreSQL + libSQL): ```bash theme={null} cargo build ``` The binary will be at `target/debug/ironclaw`. ### 3. Release Build Build optimized binary: ```bash theme={null} cargo build --release ``` The binary will be at `target/release/ironclaw`. ### 4. Run the Binary ```bash theme={null} # Development build cargo run # Or use the binary directly ./target/release/ironclaw ``` ## Build Features IronClaw supports multiple feature flags for different configurations. ### Default Features ```bash theme={null} # Build with postgres + libsql + html-to-markdown cargo build ``` Includes: * `postgres`: PostgreSQL database support * `libsql`: Embedded database support * `html-to-markdown`: HTML content conversion ### PostgreSQL Only ```bash theme={null} cargo build --no-default-features --features postgres ``` ### libSQL Only (Embedded) ```bash theme={null} cargo build --no-default-features --features libsql ``` ### All Features ```bash theme={null} cargo build --all-features ``` ## Building WASM Channels IronClaw bundles WASM channels directly into the binary. After modifying channel source code, rebuild them: ### Build Specific Channel ```bash theme={null} # Telegram channel ./channels-src/telegram/build.sh # Then rebuild IronClaw cargo build --release ``` ### Build All Channels Use the convenience script: ```bash theme={null} ./scripts/build-all.sh ``` This script: 1. Builds all bundled channels in `channels-src/` 2. Builds IronClaw with `--release` 3. Outputs binary to `target/release/ironclaw` ## Build Configuration ### Cargo.toml Overview Key configuration from `Cargo.toml`: ```toml theme={null} [package] name = "ironclaw" version = "0.13.1" edition = "2024" rust-version = "1.92" [features] default = ["postgres", "libsql", "html-to-markdown"] postgres = [...] libsql = ["dep:libsql"] integration = [] html-to-markdown = ["dep:html-to-markdown-rs", "dep:readabilityrs"] ``` ### Build Profiles #### Development (default) ```bash theme={null} cargo build ``` * Fast compilation * Debug symbols included * No optimizations #### Release ```bash theme={null} cargo build --release ``` * Full optimizations * Stripped debug symbols * Slower compilation #### Distribution ```bash theme={null} cargo build --profile dist ``` * Used by `cargo-dist` for releases * Thin LTO for smaller binaries * Inherits from release profile ## Platform-Specific Builds ### macOS ```bash theme={null} # Intel Mac rustup target add x86_64-apple-darwin cargo build --release --target x86_64-apple-darwin # Apple Silicon rustup target add aarch64-apple-darwin cargo build --release --target aarch64-apple-darwin ``` ### Linux ```bash theme={null} # x86_64 rustup target add x86_64-unknown-linux-gnu cargo build --release --target x86_64-unknown-linux-gnu # ARM64 rustup target add aarch64-unknown-linux-gnu cargo build --release --target aarch64-unknown-linux-gnu ``` ### Windows ```bash theme={null} # MSVC toolchain rustup target add x86_64-pc-windows-msvc cargo build --release --target x86_64-pc-windows-msvc ``` ## Cross-Compilation For cross-compilation, use [cross](https://github.com/cross-rs/cross): ```bash theme={null} cargo install cross # Build for ARM64 Linux on x86_64 cross build --release --target aarch64-unknown-linux-gnu ``` ## Troubleshooting ### Missing wasm32-wasip2 Target **Error**: `error: can't find target wasm32-wasip2` **Solution**: ```bash theme={null} rustup target add wasm32-wasip2 ``` ### wasm-tools Not Found **Error**: Build script fails with "wasm-tools not found" **Solution**: ```bash theme={null} cargo install wasm-tools --locked ``` ### PostgreSQL Connection Failed **Error**: `could not connect to server` **Solution**: ```bash theme={null} # Check PostgreSQL is running pg_isready # Start PostgreSQL brew services start postgresql@15 # macOS sudo systemctl start postgresql # Linux # Verify database exists psql -l | grep ironclaw ``` ### pgvector Extension Missing **Error**: `extension "vector" is not available` **Solution**: ```bash theme={null} # Install pgvector brew install pgvector # macOS sudo apt install postgresql-15-pgvector # Ubuntu # Enable in database psql ironclaw -c "CREATE EXTENSION vector;" ``` ### OpenSSL Errors (Linux) **Error**: `could not find system library 'openssl'` **Solution**: ```bash theme={null} # Ubuntu/Debian sudo apt-get install libssl-dev pkg-config # Fedora/RHEL sudo dnf install openssl-devel pkg-config ``` ### Compilation Memory Issues **Error**: Compiler runs out of memory **Solution**: ```bash theme={null} # Reduce parallel jobs cargo build --release -j 2 # Or set in ~/.cargo/config.toml [build] jobs = 2 ``` ### Linker Errors on macOS **Error**: `ld: library not found` **Solution**: ```bash theme={null} # Install Xcode Command Line Tools xcode-select --install ``` ## Build Scripts IronClaw includes convenience scripts for common build tasks: ### dev-setup.sh Complete development environment setup: ```bash theme={null} ./scripts/dev-setup.sh ``` * Checks dependencies * Adds WASM targets * Installs wasm-tools * Runs initial build and tests ### build-all.sh Full release build with channels: ```bash theme={null} ./scripts/build-all.sh ``` * Builds all WASM channels * Builds IronClaw with `--release` * Outputs to `target/release/ironclaw` ## Build Time Optimization ### Use Cargo Cache ```bash theme={null} # Install sccache cargo install sccache # Configure in ~/.cargo/config.toml [build] rustc-wrapper = "sccache" ``` ### Incremental Compilation Enabled by default for debug builds: ```toml theme={null} # In Cargo.toml [profile.dev] incremental = true ``` ### Parallel Builds Maximize CPU usage: ```bash theme={null} # Use all CPU cores (default) cargo build --release # Limit parallel jobs cargo build --release -j 4 ``` ## Verifying Your Build ### Check Version ```bash theme={null} ./target/release/ironclaw --version # ironclaw 0.13.1 ``` ### Run Tests ```bash theme={null} cargo test ``` See [Running Tests](/development/testing) for detailed testing guide. ### Run the REPL ```bash theme={null} ./target/release/ironclaw ``` You should see the IronClaw interactive prompt. ## Next Steps After building successfully: 1. **Configure IronClaw**: Run `ironclaw onboard` for setup wizard 2. **Run Tests**: See [Running Tests](/development/testing) 3. **Start Contributing**: Read [Contributing Guide](/development/contributing) 4. **Check Feature Parity**: Review [Feature Parity](/development/feature-parity) ## Additional Resources * [Rust Installation Guide](https://rustup.rs) * [Cargo Book](https://doc.rust-lang.org/cargo/) * [WASM Component Model](https://github.com/WebAssembly/component-model) * [PostgreSQL Downloads](https://www.postgresql.org/download/) * [pgvector Documentation](https://github.com/pgvector/pgvector)