Installing HORUS

Get HORUS up and running in 5 minutes. We'll install Rust, build HORUS, and verify everything works.

Platform Support

HORUS works on systems with POSIX shared memory support:

Prerequisites

Required:

• Operating System: Linux (Ubuntu 20.04+) or macOS 11+
• Rust 1.70+: We'll install this in Step 1
• Build Tools: C compiler, pkg-config, and system libraries

  # Ubuntu/Debian - COMPLETE dependencies (copy-paste this!)
  sudo apt update && sudo apt install \
    build-essential \
    pkg-config \
    libudev-dev \
    libssl-dev \
    libasound2-dev
  
  # Fedora/RHEL
  sudo dnf groupinstall "Development Tools"
  sudo dnf install pkg-config systemd-devel openssl-devel alsa-lib-devel
  
  # Arch Linux
  sudo pacman -S base-devel pkg-config systemd openssl alsa-lib
  
  # macOS
  xcode-select --install
  brew install pkg-config openssl
  

• 10-15 minutes: For first-time installation
• Internet connection: To download dependencies

Don't worry if you don't have:

• Rust (we'll install it)
• Git (we'll install it)
• Experience with systems programming (not needed!)

Quick Install (Recommended)

Copy and paste these commands into your terminal:

# 1. Install Rust (takes ~2 minutes)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 2. Clone HORUS
git clone https://github.com/horus-robotics/horus.git
cd horus

# 3. Run automated installer (takes ~5 minutes)
./install.sh

# 4. Verify it works
horus --version

# 5. Run full verification (optional but recommended)
./verify.sh

If you see horus 0.3.0 (or similar) and verify.sh shows green checkmarks, you're all set! Skip to Next Steps.

What the installer does:

• Builds the horus CLI tool
• Installs six core libraries to ~/.horus/cache/:
  • horus_core - Core runtime and scheduler
  • horus - Main framework library
  • horus_macros - Procedural macros for simplified syntax
  • horus_library - Standard message types and nodes
  • horus_c - C bindings with headers
  • horus_py - Python bindings (auto-installed if Python 3.9+ detected)
• Tracks the installed version for automatic updates
• Verifies installation with built-in tests

Step-by-Step Installation

Step 1: Install Rust

HORUS is built with Rust. Don't worry if you've never used it - you don't need to know Rust to use HORUS (Python and C work too!).

On Linux or macOS:

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

Follow the prompts (just press Enter for defaults).

Restart your terminal or run:

source $HOME/.cargo/env

Verify Rust is installed:

rustc --version
cargo --version

You should see version numbers like rustc 1.75.0.

On Windows: Use Windows Subsystem for Linux (WSL):

# In PowerShell (as Administrator)
wsl --install

# Then follow Linux instructions inside WSL

Step 2: Install Git (If You Don't Have It)

Check if you have Git:

git --version

If not, install it:

# Ubuntu/Debian
sudo apt install git

# macOS
xcode-select --install

# Fedora
sudo dnf install git

Step 3: Clone HORUS

Download the HORUS source code:

git clone https://github.com/horus-robotics/horus.git
cd horus

This creates a horus directory with all the code.

Step 4: Run the Installer

Use the automated installer to build and install everything:

./install.sh

This script:

1. Builds all HORUS packages (takes ~5 minutes)
2. Installs the horus CLI to ~/.cargo/bin/
3. Installs core libraries to ~/.horus/cache/
4. Saves version information for updates
5. Runs verification tests

You'll see colored output showing progress - green checkmarks mean success!

Step 5: Verify Installation

Test that the horus command works:

horus --version

You should see:

horus 0.3.0

Try the help command:

horus --help

You should see a list of available commands like new, run, dashboard, etc.

Step 6: Run Full Verification (Recommended)

Run the comprehensive verification script to ensure everything is working:

./verify.sh

What it checks:

• [+] System requirements (Rust, Cargo, C compiler, pkg-config)
• [+] System libraries (OpenSSL, udev)
• [+] HORUS binary and installation path
• [+] Core libraries in ~/.horus/cache/
• [+] All subcommands (new, run, dashboard, pkg, env, auth)
• [+] Build verification (cargo check with 0 warnings)
• [+] Debug binary functionality
• [+] Optional features (Python/C bindings)
• [+] Disk usage stats

Example output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   HORUS Installation Verification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

System Requirements:
  ✓ Rust: 1.75.0 (>= 1.70 required)
  ✓ Cargo: 1.75.0
  ✓ C compiler: gcc

HORUS Installation:
  ✓ Binary: v0.3.0 at ~/.cargo/bin/horus
  ✓ In PATH: Yes (correct binary)

Functionality Tests:
  ✓ Command: --version
  ✓ Command: --help
  ✓ All subcommands: Accessible
  ✓ Build: cargo check passes (0 warnings)
  ✓ Binary: Debug build functional

Summary:
   Perfect! Everything looks good.
  HORUS is properly installed and ready to use.

If there are issues:

• [!] Warnings - Minor issues, HORUS will work but review suggestions
• Errors - Critical problems, run ./recovery_install.sh to fix

Pro tip: Run ./verify.sh anytime you:

• Update HORUS (./update.sh)
• Suspect installation problems
• Want to check system health before deployment
• Contribute to HORUS (ensures no warnings)

Python Support

Python bindings are automatically installed by ./install.sh if Python 3.9+ is detected.

To verify Python bindings work:

python3 -c "import horus; print('Python bindings work!')"

Manual installation (if automatic installation was skipped):

# 1. Install maturin (Python build tool)
pip install maturin

# 2. Navigate to Python bindings
cd horus_py

# 3. Build and install (takes ~3 minutes)
maturin develop --release

See Python Bindings for complete API documentation and examples.

Optional: C Support

Want to integrate C code? Build the C bindings:

cd horus_c
cargo build --release

The shared library will be in target/release/:

• libhorus_c.so (Linux)
• libhorus_c.dylib (macOS)

See Multi-Language for C examples.

Platform-Specific Notes

Linux (Ubuntu/Debian)

Most things "just work" on Linux. If you hit build errors:

sudo apt update && sudo apt install \
  build-essential \
  pkg-config \
  libudev-dev \
  libssl-dev \
  libasound2-dev

Linux (Fedora/RHEL)

sudo dnf groupinstall "Development Tools"

macOS

Install Xcode Command Line Tools if you haven't:

xcode-select --install

Note: macOS has smaller shared memory limits than Linux. For most applications this is fine, but if you're moving lots of large messages, Linux is better.

Windows

Use WSL (Windows Subsystem for Linux):

1. Open PowerShell as Administrator
2. Run: wsl --install
3. Restart your computer
4. Follow the Linux installation steps inside WSL

Understanding Shared Memory

HORUS uses /dev/shm for ultra-fast communication between components.

Check available space:

df -h /dev/shm

You should have at least 256MB. Most systems have 1-2GB.

If you need more space (advanced):

# Temporarily increase to 2GB
sudo mount -o remount,size=2G /dev/shm

# Make permanent: edit /etc/fstab (requires sudo)
# Add line: tmpfs /dev/shm tmpfs defaults,size=2G 0 0

Updating HORUS

To update to the latest version, use the smart update script:

# Navigate to HORUS directory
cd horus

# Run the update script (handles git pull automatically)
./update.sh

The update script will:

• Check for uncommitted changes (offers to stash)
• Fetch and show what's new from the repository
• Ask permission before pulling
• Only rebuild what changed (much faster than reinstalling)
• Verify the update succeeded

Alternative: Full reinstall (if update.sh has issues):

git pull
./install.sh

Uninstalling

To completely remove HORUS:

# Navigate to HORUS directory
cd horus

# Run the uninstaller
./uninstall.sh

The uninstaller will:

1. Remove the horus CLI binary (~/.cargo/bin/horus)
2. Remove all cached libraries (~/.horus/cache/)
3. Ask if you want to remove ~/.horus/ (contains auth, config, registry data)
4. Clean up shared memory files:
   • /dev/shm/horus/topics/ (Link communication)
   • /dev/shm/horus/heartbeats/ (Node monitoring)
   • /dev/shm/horus_logs (Log buffer)
5. Leave project-local .horus/ directories untouched

Manual uninstall (if needed):

# Remove CLI tool
cargo uninstall horus

# Remove global cache and config
rm -rf ~/.horus/

# Remove source code
rm -rf ~/horus/  # or wherever you cloned it

# Clean up shared memory
rm -rf /dev/shm/horus/
rm -f /dev/shm/horus_logs

Troubleshooting

Having installation issues? See the Troubleshooting & Maintenance Guide for:

• Common installation errors and fixes
• System dependency issues
• Update and recovery scripts (update.sh, verify.sh, recovery_install.sh)
• Platform-specific problems
• 15+ solved issues with detailed solutions

Next Steps

Now that HORUS is installed, let's build something!

1. Quick Start Tutorial Build your first HORUS application in 10 minutes

2. CLI Reference Learn all the horus commands

3. Examples See real HORUS applications

Ready to start? Head to the Quick Start