Skip to main content

​
Soul Kernel Setup Guide

This guide covers setting up Soul Kernel on various platforms and configurations.

​
📋 Table of Contents

​
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

Here’s the best way to set up and develop with Rust on macOS, optimized for both speed and ergonomics:

​
✅ 1. Install Rust

Use rustup to manage Rust versions: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Installs cargo, rustc, rustfmt, etc.

​
✅ 2. Set Up a Modern Rust Dev Environment

Toolchain 
rustup update                       # keep toolchain fresh
rustup component add clippy rustfmt # linter + formatter
rustup target add aarch64-apple-darwin # Apple-Silicon target
Project Starter 
cargo new my-project --lib
cd my-project
cargo build

​
✅ 3. Editor Setup (VS Code)

Install extensions:
  • Rust Analyzer (rust-lang.rust-analyzer) — best LSP
  • CodeLLDB — native debugging
Ensure rust-analyzer is enabled in VS Code settings.

​
✅ 4. Use cargo Efficiently

CommandPurpose
cargo buildCompile debug build
cargo checkFast type-check only
cargo testRun unit tests
cargo fmtFormat code
cargo clippyLint with Clippy
  • 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

If you want consistent dev environments across teams, try nix or devbox.

​
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
  3. Install Git Bash (recommended)
  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
  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
  • Ensure Visual Studio Build Tools are installed
  • Run from “x64 Native Tools Command Prompt”

​
Next Steps

Need help? File an issue on GitHub 🤝