Build from Source

Overview

Jarvis is a hybrid project with Rust (jarvis-rs) and Python (AI integration) components. Building from source gives you access to the latest features and allows customization.

Building from source requires macOS 13+. Windows and Linux support is experimental.

Prerequisites

System Requirements

macOS
Linux (Experimental)
Windows (Experimental)

# Check versions
sw_vers -productVersion  # macOS 13.0+
xcodebuild -version      # Xcode 14.0+
rustc --version          # 1.75.0+
python3 --version        # Python 3.10+
swift --version          # Swift 5.9+

Install Xcode Command Line Tools

xcode-select --install

Install Rust

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

Install Python 3.10+

brew install python@3.10

# Ubuntu/Debian
sudo apt update
sudo apt install build-essential pkg-config libssl-dev \
  libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  libxdo-dev python3.10 python3-pip

# Arch Linux
sudo pacman -S base-devel webkit2gtk gtk3 libappindicator-gtk3 \
  xdotool python python-pip

Linux support is experimental. Some features (Metal renderer, macOS-specific APIs) will not work.

Automated Build

Quick Start

The setup.sh script handles the complete build process:

Clone the repository

git clone https://github.com/dyoburon/jarvis.git
cd jarvis

Run the setup script

./setup.sh

This will:

Create a Python virtual environment
Install Python dependencies
Build the Rust workspace
Build the Swift Metal app (macOS only)
Create default config directory

Configure environment

Copy .env.example to .env and add your API keys:

cp .env.example .env
nano .env  # or your preferred editor

.env

CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token
GOOGLE_API_KEY=your-gemini-api-key

Run Jarvis

./start.sh

Setup Script Deep Dive

The setup.sh script performs these steps:

View setup.sh breakdown

#!/bin/bash
set -e  # Exit on error

# 1. Create Python virtual environment
if [ ! -d ".venv" ]; then
    echo "Creating virtual environment..."
    python3 -m venv .venv
fi

# 2. Activate venv and install dependencies
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# 3. Build Rust workspace (jarvis-rs)
echo "Building Rust workspace..."
cd jarvis-rs
cargo build --release
cd ..

# 4. Build Swift Metal app (macOS only)
if [ "$(uname)" == "Darwin" ]; then
    echo "Building Metal app..."
    cd metal-app
    swift build -c release
    cd ..
fi

# 5. Create config directory with defaults
mkdir -p ~/.config/jarvis
if [ ! -f ~/.config/jarvis/config.toml ]; then
    cp docs/examples/config.toml ~/.config/jarvis/config.toml
fi

echo "Setup complete! Run './start.sh' to launch Jarvis."

Manual Build

Build Rust Components

Navigate to Rust workspace

cd jarvis-rs

Build all crates

cargo build --release

This compiles all 10 workspace crates:

jarvis-app (main binary)
jarvis-tiling
jarvis-renderer
jarvis-ai
jarvis-social
jarvis-config
jarvis-webview
jarvis-common
jarvis-platform
jarvis-relay

Run the binary

./target/release/jarvis

CLI options:

jarvis --help
jarvis -e "echo hello"        # Execute command
jarvis -d ~/code               # Start in directory
jarvis --config custom.toml    # Use custom config
jarvis --log-level debug       # Set log level

Build Python Components

Create virtual environment

python3 -m venv .venv
source .venv/bin/activate

Install dependencies

pip install -r requirements.txt

Key dependencies:

anthropic - Claude API client
google-generativeai - Gemini API client
whisper - Speech-to-text
aiohttp - Async HTTP
python-dotenv - Environment variables
rich - Terminal formatting

Run main.py (optional)

The Python stack is optional for Rust-only builds:

python main.py

Build Swift Metal App (macOS)

Navigate to Metal app

cd metal-app

Build with Swift

swift build -c release

Output: .build/release/JarvisBootup

Run standalone

.build/release/JarvisBootup

Development Build

For faster iteration during development:

# Debug build (faster compile, slower runtime)
cd jarvis-rs
cargo build

# Run with debug symbols and logging
cargo run -- --log-level debug

# Watch for changes and rebuild
cargo install cargo-watch
cargo watch -x run

Debug builds include symbols for debugging but are 5-10x slower than release builds.

Cargo Workspace Structure

The jarvis-rs/Cargo.toml defines a workspace with shared dependencies:

[workspace]
resolver = "2"
members = [
    "crates/jarvis-app",
    "crates/jarvis-common",
    "crates/jarvis-config",
    "crates/jarvis-platform",
    "crates/jarvis-tiling",
    "crates/jarvis-renderer",
    "crates/jarvis-ai",
    "crates/jarvis-social",
    "crates/jarvis-webview",
    "crates/jarvis-relay",
]

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
wry = "0.47"
# ...50+ more dependencies

[profile.release]
lto = "thin"
codegen-units = 1
strip = "symbols"
panic = "abort"

Optimized Release Build

For maximum performance:

cd jarvis-rs

# Build with full optimizations
RUSTFLAGS="-C target-cpu=native" cargo build --release

# Build with Link-Time Optimization (slower build, faster binary)
cargo build --release --config profile.release.lto=true

target-cpu=native enables CPU-specific optimizations but reduces portability.

Troubleshooting

Rust Compilation Errors

error: linker 'cc' not found

macOS: Install Xcode Command Line Tools:

xcode-select --install

Linux: Install build tools:

sudo apt install build-essential  # Debian/Ubuntu
sudo pacman -S base-devel         # Arch

error: failed to run custom build command for 'openssl-sys'

Install OpenSSL development headers:macOS:

brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)

Linux:

sudo apt install libssl-dev pkg-config

error: could not find system library 'wry'

Install WebView dependencies:Linux:

sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev

Python Build Issues

ModuleNotFoundError: No module named 'whisper'

Ensure you’re in the virtual environment:

source .venv/bin/activate
pip install -r requirements.txt

SSL: CERTIFICATE_VERIFY_FAILED

Update SSL certificates:macOS:

/Applications/Python\ 3.10/Install\ Certificates.command

Swift Build Errors (macOS)

error: unable to spawn process (No such file or directory)

Install Xcode:

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

error: SDK does not contain 'libarclite'

Update Xcode to 14.0+ (requires macOS 12.5+):

softwareupdate --list
softwareupdate --install "Xcode-14.3"

Cross-Compilation

Build for Multiple Targets

# Install target toolchains
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin

# Build for Intel Macs
cargo build --release --target x86_64-apple-darwin

# Build for Apple Silicon
cargo build --release --target aarch64-apple-darwin

# Create universal binary (macOS)
lipo -create \
  target/x86_64-apple-darwin/release/jarvis \
  target/aarch64-apple-darwin/release/jarvis \
  -output jarvis-universal

Packaging

Create a distributable package:

# Run the package script
./package.sh

# Creates:
# jarvis-macos-aarch64.tar.gz (Apple Silicon)
# jarvis-macos-x86_64.tar.gz (Intel)

The package includes:

Compiled binary (jarvis)
Default config (config.toml)
Python dependencies (frozen)
HTML/JS/CSS assets
README and LICENSE

Source References

setup.sh - Automated setup script
start.sh - Launch script with venv activation
package.sh - Distribution packaging
jarvis-rs/Cargo.toml - Workspace configuration
requirements.txt - Python dependencies
metal-app/Package.swift - Swift package manifest
README.md - Project overview

Architecture

Networking

Advanced

Build from Source

Overview

Prerequisites

System Requirements

Automated Build

Quick Start

Setup Script Deep Dive

Manual Build

Build Rust Components

Build Python Components

Build Swift Metal App (macOS)

Development Build

Cargo Workspace Structure

Optimized Release Build

Troubleshooting

Rust Compilation Errors

Python Build Issues

Swift Build Errors (macOS)

Cross-Compilation

Build for Multiple Targets

Packaging

Source References

Architecture

Networking

Advanced

​Overview

​Prerequisites

​System Requirements

​Automated Build

​Quick Start

​Setup Script Deep Dive

​Manual Build

​Build Rust Components

​Build Python Components

​Build Swift Metal App (macOS)

​Development Build

​Cargo Workspace Structure

​Optimized Release Build

​Troubleshooting

​Rust Compilation Errors

​Python Build Issues

​Swift Build Errors (macOS)

​Cross-Compilation

​Build for Multiple Targets

​Packaging

​Source References

Overview

Prerequisites

System Requirements

Automated Build

Quick Start

Setup Script Deep Dive

Manual Build

Build Rust Components

Build Python Components

Build Swift Metal App (macOS)

Development Build

Cargo Workspace Structure

Optimized Release Build

Troubleshooting

Rust Compilation Errors

Python Build Issues

Swift Build Errors (macOS)

Cross-Compilation

Build for Multiple Targets

Packaging

Source References