​

Soul Kernel Setup Guide

​

📋 Table of Contents

• System Requirements
• Platform Setup
  • macOS
  • Linux
  • Windows
• Development Setup
• Shell-Specific Setup
• Troubleshooting

​

System Requirements

​

Minimum Requirements

• CPU: 64-bit processor (x86_64 or ARM64)
• RAM: 4GB minimum, 8GB recommended
• Storage: 2GB free space
• OS: macOS 11+, Ubuntu 20.04+, Windows 10+

​

Supported Architectures

• x86_64 (Intel/AMD)
• aarch64 (Apple Silicon, ARM64)
• Cross-compilation to iOS, Android, Physical AI devices

​

Platform Setup

​

macOS

​

✅ 1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Installs cargo, rustc, rustfmt, etc.

​

✅ 2. Set Up a Modern Rust Dev Environment

rustup update                       # keep toolchain fresh
rustup component add clippy rustfmt # linter + formatter
rustup target add aarch64-apple-darwin # Apple-Silicon target

cargo new my-project --lib
cd my-project
cargo build

​

✅ 3. Editor Setup (VS Code)

• Rust Analyzer (rust-lang.rust-analyzer) — best LSP
• CodeLLDB — native debugging

Ensure rust-analyzer is enabled in VS Code settings.

​

✅ 4. Use cargo Efficiently

​

✅ 5. Recommended Add-ons

• cargo-watch — auto-rebuild on file change
  cargo install cargo-watch
  cargo watch -x check -x test
  
• just — task runner like Make but Rust-y
  cargo install just
  

​

✅ 6. Apple-Silicon Gotchas

• Ensure dependencies compile for aarch64-apple-darwin.
• Some crates (e.g. openssl) require Xcode CLI tools:
  xcode-select --install
  

​

✅ 7. Optional: Use nix for reproducible builds

​

Linux

1. Update System Packages
   sudo apt update && sudo apt upgrade -y
   
2. Install Build Essentials
   sudo apt install -y build-essential pkg-config libssl-dev
   
3. Install Rust
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source "$HOME/.cargo/env"
   
4. Install Additional Dependencies
   # For gRPC development
   sudo apt install -y protobuf-compiler
   
   # For cross-compilation
   sudo apt install -y gcc-aarch64-linux-gnu
   

​

Windows

1. Install Visual Studio Build Tools
   • Download from Visual Studio
   • Select “Desktop development with C++”
2. Install Rust
   • Download and run rustup-init.exe
   • Follow the installer prompts
3. Install Git Bash (recommended)
   • Download from git-scm.com
4. Set Environment Variables
   # Add to PATH if not already done
   $env:PATH += ";$env:USERPROFILE\.cargo\bin"
   

​

Development Setup

​

1. Clone Repository

git clone https://github.com/soul-kernel/soul-kernel.git
cd soul-kernel

​

2. Install Rust Toolchain

# Install specific version from rust-toolchain.toml
cd kernel
rustup show

​

3. Build Project

# Debug build
cargo build

# Release build with optimizations
cargo build --release

# Run tests
cargo test

# Run with verbose output
RUST_LOG=debug cargo run

​

4. IDE Configuration

​

VS Code

1. Install extensions:
   • rust-analyzer
   • CodeLLDB (for debugging)
   • Even Better TOML
2. Create .vscode/settings.json:
   {
     "rust-analyzer.cargo.features": "all",
     "rust-analyzer.checkOnSave.command": "clippy",
     "rust-analyzer.inlayHints.enable": true,
     "editor.formatOnSave": true
   }
   

​

IntelliJ IDEA / CLion

1. Install Rust plugin
2. Open project root
3. Configure Rust toolchain in Settings

​

5. Pre-commit Hooks (optional)

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: local
    hooks:
      - id: rust-fmt
        name: Rust Format
        entry: cargo fmt --
        language: system
        files: '\.rs$'
      - id: rust-clippy
        name: Rust Clippy
        entry: cargo clippy -- -D warnings
        language: system
        files: '\.rs$'
EOF

# Install hooks
pre-commit install

​

Shell-Specific Setup

​

iOS Shell (React Native)

1. Install Node.js & Yarn
   brew install node yarn
   
2. Install CocoaPods
   sudo gem install cocoapods
   
3. Setup iOS Dependencies
   cd shells/ios
   yarn install
   cd ios && pod install
   

​

Unity Shell

1. Install Unity Hub
   • Download from unity.com
2. Install Unity 2022.3 LTS
   • Add iOS/Android build support
3. Import Soul Kernel Package
   # In Unity Package Manager
   Add package from git URL:
   https://github.com/soul-kernel/unity-soul-kernel.git
   

​

Physical AI Gateway

1. Flash JetPack 5.1+ (for NVIDIA Jetson)
   • Use NVIDIA SDK Manager
2. Install Rust on Physical AI Device
   # SSH into device
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
3. Install dora-rs
   cargo install dora-cli
   

​

Environment Variables

​

Development

# Enable debug logging
export RUST_LOG=soul_kernel=debug

# Set custom data directory
export SOUL_DATA_DIR=/path/to/data

# Enable backtrace on panic
export RUST_BACKTRACE=1

​

Production

# Optimize for size
export CARGO_PROFILE_RELEASE_LTO=true
export CARGO_PROFILE_RELEASE_OPT_LEVEL="z"

# Set production endpoints
export SOUL_SYNC_ENDPOINT=https://api.soul-kernel.io

​

Troubleshooting

​

Common Issues

​

1. Rust Installation Fails

# Remove old installation
rustup self uninstall

# Clean install with verbose output
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -v

​

2. Cargo Build Errors

# Clear cache
cargo clean

# Update dependencies
cargo update

# Check for outdated deps
cargo outdated

​

3. Binary Size Too Large

# Check size breakdown
cargo bloat --release

# Strip symbols manually
strip target/release/soul-kernel

​

4. Cross-compilation Issues

# Install target
rustup target add aarch64-apple-ios

# Use cargo-xcode for iOS
cargo install cargo-xcode
cargo xcode

​

Platform-Specific Issues

​

macOS: “xcrun: error”

sudo xcode-select --switch /Applications/Xcode.app

​

Linux: Missing Libraries

# Find missing libs
ldd target/release/soul-kernel

# Install common missing deps
sudo apt install -y libssl-dev pkg-config

​

Windows: Link Errors

• Ensure Visual Studio Build Tools are installed
• Run from “x64 Native Tools Command Prompt”

​

Next Steps

• Read the Developer Onboarding Guide
• Explore the Architecture Documentation
• Join our Discord Community