Installation Guide

Complete installation instructions for ruv-FANN across all platforms and use cases.

🚀 Quick Installation

Rust (Recommended)

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Add to your Rust project
cargo add ruv-fann semantic-cartan-matrix ruv-swarm

JavaScript/TypeScript

# Install Node.js SDK
npm install ruv-swarm

# Install CLI tools globally
npm install -g claude-flow ruv-swarm

Python (via PyO3)

# Install Python bindings
pip install ruv-swarm-py

# Install with ML dependencies
pip install ruv-swarm-py[ml,neural,async]

🖥️ Platform-Specific Installation

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt update
sudo apt install build-essential pkg-config libssl-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install SIMD support
sudo apt install libc6-dev

# Verify installation
cargo --version
rustc --version

macOS

# Install Xcode command line tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install via Homebrew (alternative)
brew install rust

Windows

# Download and run rustup-init.exe from https://rustup.rs/

# Or use Chocolatey
choco install rust

# Or use Scoop
scoop install rust

# Install Microsoft C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

Docker

# Use official Rust image
FROM rust:1.75-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    pkg-config \
    libssl-dev \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy and build project
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN cargo build --release

# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY --from=0 /app/target/release/ruv-fann /usr/local/bin/
CMD ["ruv-fann"]

🔧 Feature Configuration

Core Features

[dependencies]
ruv-fann = { version = "0.3", features = ["default"] }

# Available features:
# "std"          - Standard library support (default)
# "simd"         - SIMD acceleration (recommended)
# "parallel"     - Multi-threading support
# "wasm"         - WebAssembly compilation
# "gpu"          - GPU acceleration
# "embedded"     - Embedded/no_std support

SIMD Acceleration

[dependencies]
ruv-fann = { version = "0.3", features = ["simd", "avx2"] }

# Platform-specific SIMD:
# "sse2"    - Basic SSE2 (x86/x64)
# "sse4.1"  - Advanced SSE (x86/x64) 
# "avx"     - AVX support (x86/x64)
# "avx2"    - AVX2 support (x86/x64)
# "neon"    - ARM NEON support

WebAssembly

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

# Build for web
wasm-pack build --target web --features wasm

# Build for Node.js
wasm-pack build --target nodejs --features wasm,simd

GPU Acceleration

[dependencies]
ruv-fann = { version = "0.3", features = ["gpu", "cuda"] }

# GPU features:
# "opencl"  - OpenCL support
# "cuda"    - NVIDIA CUDA support  
# "vulkan"  - Vulkan compute
# "webgpu"  - WebGPU (WASM only)

🔬 Development Installation

Full Development Setup

# Clone repository
git clone https://github.com/ruvnet/ruv-FANN.git
cd ruv-FANN

# Install development dependencies
rustup component add clippy rustfmt
cargo install cargo-watch cargo-audit cargo-tarpaulin

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run development setup
make dev-setup

IDE Configuration

VS Code

{
  "extensions.recommendations": [
    "rust-lang.rust-analyzer",
    "serayuzgur.crates",
    "tamasfe.even-better-toml",
    "vadimcn.vscode-lldb"
  ],
  "rust-analyzer.cargo.features": [
    "std", "simd", "parallel"
  ],
  "rust-analyzer.checkOnSave.command": "clippy"
}

CLion/IntelliJ

<!-- In .idea/runConfigurations/ruv_fann.xml -->
<configuration name="ruv-fann" type="CargoCommandRunConfiguration">
  <option name="command" value="run --features std,simd,parallel" />
  <option name="workingDirectory" value="$PROJECT_DIR$" />
  <option name="emulateTerminal" value="true" />
</configuration>

🌐 WebAssembly Installation

Browser Deployment

# Build optimized WASM
wasm-pack build --release --target web \
  --features wasm,simd \
  --out-dir pkg

# Optimize with wasm-opt
wasm-opt -Oz -o pkg/ruv_fann_bg.wasm pkg/ruv_fann_bg.wasm

# Create HTML wrapper
cat > index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
    <title>ruv-FANN Demo</title>
    <script type="module">
        import init, { NeuralNetwork } from './pkg/ruv_fann.js';
        
        async function run() {
            await init();
            
            const net = new NeuralNetwork(3, [4, 2], 1);
            console.log('Neural network created!');
        }
        
        run().catch(console.error);
    </script>
</head>
<body>
    <h1>ruv-FANN WebAssembly Demo</h1>
    <p>Check browser console for output.</p>
</body>
</html>
EOF

# Serve locally
python -m http.server 8000

Node.js Integration

# Build for Node.js
wasm-pack build --target nodejs --features wasm

# Install in Node project
npm install ./pkg

# Use in Node.js
cat > demo.js << 'EOF'
const { NeuralNetwork } = require('./pkg');

async function main() {
    const net = new NeuralNetwork(3, [4, 2], 1);
    console.log('Neural network ready!');
}

main().catch(console.error);
EOF

node demo.js

📱 Embedded Installation

ARM Cortex-M

[dependencies]
ruv-fann = { 
    version = "0.3", 
    default-features = false,
    features = ["embedded", "arm"]
}

# Target configuration
[target.thumbv7em-none-eabihf]
rustflags = ["-C", "target-cpu=cortex-m4", "-C", "target-feature=+fp"]

RISC-V

[dependencies]
ruv-fann = { 
    version = "0.3", 
    default-features = false,
    features = ["embedded", "riscv"]
}

ESP32

# Install ESP-IDF
curl -LO https://github.com/esp-rs/rust-build/releases/latest/download/install-rust-toolchain.sh
chmod +x install-rust-toolchain.sh
./install-rust-toolchain.sh

# Configure for ESP32
cat > .cargo/config.toml << 'EOF'
[target.xtensa-esp32-espidf]
linker = "ldproxy"

[env]
ESP_IDF_VERSION = "v4.4"
EOF

🧪 Testing Installation

Verify Core Installation

# Test Rust installation
cat > test_installation.rs << 'EOF'
use ruv_fann::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("🧪 Testing ruv-FANN installation...");
    
    let mut net = NeuralNetwork::builder()
        .input_size(2)
        .hidden_layers(&[3])
        .output_size(1)
        .build()?;
    
    let input = vec![0.5, 0.3];
    let output = net.run(&input)?;
    
    println!("✅ Neural network test successful!");
    println!("   Input: {:?}", input);
    println!("   Output: {:?}", output);
    
    Ok(())
}
EOF

rustc test_installation.rs -o test_install
./test_install

Test SIMD Support

# Test SIMD capabilities
cat > test_simd.rs << 'EOF'
use ruv_fann::simd::*;

fn main() {
    println!("🔍 SIMD Capability Detection:");
    
    #[cfg(target_feature = "sse2")]
    println!("✅ SSE2 supported");
    
    #[cfg(target_feature = "avx")]
    println!("✅ AVX supported");
    
    #[cfg(target_feature = "avx2")]
    println!("✅ AVX2 supported");
    
    println!("🚀 SIMD features compiled in");
}
EOF

rustc --cfg 'feature="simd"' test_simd.rs -o test_simd
./test_simd

Test Swarm Coordination

# Test swarm functionality
npx ruv-swarm test --self-check --verbose

# Expected output:
# ✅ WASM runtime initialized
# ✅ Agent spawning functional
# ✅ Task orchestration working
# ✅ Memory coordination active
# ✅ All systems operational

🚨 Troubleshooting

Common Issues

Rust Compilation Errors

# Update Rust toolchain
rustup update

# Clear cargo cache
cargo clean

# Rebuild with verbose output
cargo build --verbose

SIMD Not Working

# Check CPU capabilities
lscpu | grep -i simd
cat /proc/cpuinfo | grep flags

# Compile with specific CPU target
RUSTFLAGS="-C target-cpu=native" cargo build --release

WebAssembly Build Fails

# Install required targets
rustup target add wasm32-unknown-unknown
rustup target add wasm32-wasi

# Update wasm-pack
cargo install wasm-pack --force

# Clear WASM cache
rm -rf pkg/ target/

Permission Issues (Linux/macOS)

# Fix cargo permissions
sudo chown -R $USER:$USER ~/.cargo

# Add user to relevant groups
sudo usermod -a -G docker $USER

Windows Build Errors

# Install Visual Studio Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Set environment variables
$env:RUSTFLAGS="-C target-feature=+crt-static"

# Use stable MSVC toolchain
rustup default stable-x86_64-pc-windows-msvc

📊 Verify Installation

Performance Benchmarks

# Run benchmarks to verify performance
cargo bench --features bench,simd

# Expected results:
# Neural Network Training:     ~2.5ms
# SIMD Vector Operations:      ~15ns  
# Swarm Coordination:          ~50ms
# Memory Allocation:           ~100ns

Feature Testing

# Test all features
cargo test --all-features --verbose

# Test specific components
cargo test --package ruv-fann --features simd
cargo test --package semantic-cartan-matrix
cargo test --package ruv-swarm --features std

🎯 Next Steps

After successful installation:

Quick Start - Get running in 5 minutes
Getting Started Guide - Comprehensive tutorial
API Reference - Complete API documentation
Examples - Working code samples

📞 Support

Need help with installation?

Troubleshooting - Common issues and solutions
GitHub Issues - Report installation problems
Community Resources - Get help from the community

Installation complete! 🎉 Ready to build the future of AI with ruv-FANN.