How To Install - ruvnet/ruv-FANN GitHub Wiki

How to Install ruv-FANN

A comprehensive, platform-specific installation guide for the ruv-FANN neural intelligence framework.

Prerequisites

System Requirements

Component	Minimum	Recommended
OS	Linux/macOS/Windows 10+	Ubuntu 22.04+ / macOS 13+ / Windows 11
Memory	2GB RAM	8GB+ RAM
CPU	x86_64 with SSE2	x86_64 with AVX2/ARM64
Disk Space	1GB	5GB+ for development
Network	Broadband	High-speed for swarm coordination

Required Tools

Rust Toolchain

# Install Rust (required for all platforms)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Verify installation
rustc --version
cargo --version

Node.js (for NPM/NPX usage)

# Option 1: Install via package manager
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Option 2: Use Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Verify installation
node --version  # Should be 20.x+
npm --version   # Should be 10.x+

Quick Install (NPX - No Installation Required!)

For Claude Code Users

# Initialize ruv-swarm with Claude integration
npx ruv-swarm@latest init --claude

# Follow the interactive setup

For General Usage

# Quick start with basic setup
npx ruv-swarm@latest init

# Advanced setup with all features
npx ruv-swarm@latest init --full --wasm --gpu-detect

Platform-Specific Installation

Ubuntu/Debian Linux

1. System Dependencies

# Update package lists
sudo apt update

# Install build essentials
sudo apt install -y build-essential pkg-config libssl-dev

# Install optional GPU dependencies (if available)
sudo apt install -y ocl-icd-libopencl1 opencl-headers

# For WASM development
sudo apt install -y binaryen

2. Install ruv-FANN

# Option A: Global NPM installation
npm install -g ruv-swarm

# Option B: Cargo installation (Rust native)
cargo install ruv-swarm-cli

# Option C: Build from source
git clone https://github.com/ruvnet/ruv-FANN.git
cd ruv-FANN
cargo build --release --all

3. Verify Installation

# Test NPM installation
ruv-swarm --version

# Test Cargo installation
ruv-swarm-cli --version

# Run system diagnostics
ruv-swarm init --test-system

macOS

1. Install Xcode Command Line Tools

xcode-select --install

2. Install Dependencies via Homebrew

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install pkg-config openssl

# Optional: WASM tools
brew install binaryen wabt

3. Install ruv-FANN

# Global installation
npm install -g ruv-swarm

# Or via Cargo
cargo install ruv-swarm-cli

# Verify installation
ruv-swarm --version

4. Handle macOS-Specific Issues

# If you encounter OpenSSL linking issues
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
export OPENSSL_DIR="/opt/homebrew/opt/openssl"

# For M1/M2 Macs, ensure Rosetta 2 compatibility
softwareupdate --install-rosetta --agree-to-license

Windows

1. Install Prerequisites

# Install via Chocolatey (run as Administrator)
choco install nodejs rust msys2

# Or install manually:
# - Download Node.js from https://nodejs.org
# - Download Rust from https://rustup.rs
# - Install Visual Studio Build Tools

2. Setup Build Environment

# Install Visual Studio Build Tools 2022
# Download from: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

# Or use winget
winget install Microsoft.VisualStudio.2022.BuildTools

3. Install ruv-FANN

# Global NPM installation
npm install -g ruv-swarm

# Test installation
ruv-swarm --version

# Initialize with Windows-specific options
ruv-swarm init --windows --no-unix-sockets

4. Windows-Specific Configuration

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

# For PowerShell execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Development Environment Setup

1. Clone the Repository

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

2. Setup Workspace

# Install all dependencies
cargo build --all

# Install development tools
cargo install cargo-watch cargo-audit cargo-outdated

# Setup pre-commit hooks
cargo install cargo-husky

3. Build All Components

# Build core libraries
cd Semantic_Cartan_Matrix
cargo build --release --all

# Build ruv-swarm
cd ../ruv-swarm
cargo build --release

# Build WASM components
./build-wasm-optimized.sh

4. Run Tests

# Unit tests
cargo test --all

# Integration tests
cargo test --test integration_test

# WASM tests
wasm-pack test --node

Configuration

Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export RUV_FANN_HOME="$HOME/.ruv-fann"
export RUV_SWARM_CONFIG="$RUV_FANN_HOME/config.toml"
export RUV_LOG_LEVEL="info"

# For GPU detection
export RUV_GPU_BACKEND="auto"  # Options: auto, cpu, opencl, cuda, webgpu

# For WASM optimization
export RUV_WASM_OPTIMIZATION="size"  # Options: size, speed, debug

Create Configuration File

# Create config directory
mkdir -p ~/.ruv-fann

# Generate default config
ruv-swarm config init > ~/.ruv-fann/config.toml

Verification & Testing

System Health Check

# Run comprehensive system test
ruv-swarm init --test-all

# Expected output:
✅ Rust toolchain: 1.75.0+
✅ WASM support: Available
✅ GPU detection: OpenCL/CPU fallback
✅ Network connectivity: OK
✅ Swarm coordination: Ready
✅ Neural models: 27 loaded

Basic Functionality Test

# Test neural network creation
ruv-swarm test neural --quick

# Test swarm coordination
ruv-swarm test swarm --agents 3

# Test WASM compilation
ruv-swarm test wasm --simple

Performance Benchmark

# Run quick benchmark
ruv-swarm benchmark --quick

# Expected results:
Neural network creation: <10ms
Swarm coordination: <50ms
WASM execution: <5ms
Memory usage: <100MB

Troubleshooting

Common Issues

1. Rust Compilation Errors

# Update Rust toolchain
rustup update stable

# Clear cargo cache
cargo clean

# Rebuild with verbose output
cargo build --verbose

2. Node.js/NPM Issues

# Clear NPM cache
npm cache clean --force

# Update NPM
npm install -g npm@latest

# Fix permissions (Linux/macOS)
sudo chown -R $(whoami) ~/.npm

3. WASM Build Failures

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

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

# Rebuild WASM modules
wasm-pack build --target web --release

4. GPU Detection Issues

# Check GPU backend availability
ruv-swarm debug gpu

# Force CPU-only mode
ruv-swarm init --cpu-only

# Install GPU drivers (Ubuntu)
sudo apt install mesa-opencl-icd

5. Permission Errors (Linux/macOS)

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

# Fix npm permissions
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER /usr/local/lib/node_modules

Getting Help

Log Collection

# Enable detailed logging
export RUV_LOG_LEVEL="debug"

# Run with log output
ruv-swarm init --verbose > install.log 2>&1

# Submit logs with issue report

Community Support

GitHub Issues: https://github.com/ruvnet/ruv-FANN/issues
Discord: https://discord.gg/ruv
Documentation: https://docs.ruv.ai

Next Steps

After successful installation:

Read the Quick Start Guide: Quick-Start.md
Try the Getting Started Tutorial: Getting-Started-Guide.md
Explore Code Examples: Code-Examples.md
Learn Integration Patterns: How-To-Integrate.md

Advanced Installation Options

Docker Installation

# Pull official image
docker pull ruvnet/ruv-fann:latest

# Run with volume mounting
docker run -v $(pwd):/workspace ruvnet/ruv-fann:latest

Kubernetes Deployment

# Apply ruv-swarm operator
kubectl apply -f https://raw.githubusercontent.com/ruvnet/ruv-FANN/main/k8s/operator.yaml

# Deploy swarm cluster
kubectl apply -f examples/k8s-swarm.yaml

Edge/Embedded Installation

# Cross-compile for ARM64
cargo build --target aarch64-unknown-linux-gnu --release

# Build minimal WASM for embedded
wasm-pack build --target no-modules --release -- --features minimal

This completes the comprehensive installation guide. The installation process should work across all major platforms with clear troubleshooting steps for common issues.