Installing HORUS

This guide covers installing Rust, building HORUS, and verifying the installation. The process takes approximately 10-15 minutes.

Platform Support

HORUS has native cross-platform support:

Prerequisites

Required:

• Operating System: Linux, macOS, or Windows
  • Linux: Ubuntu 20.04+ recommended (fastest shared memory)
  • macOS: Native support using /tmp/horus/
  • Windows: Native support using %TEMP%\horus\
• Rust 1.70+: We'll install this in Step 1
• Build Tools & System Libraries: Build tools, pkg-config, and all required development libraries
  Copy

  # Ubuntu/Debian/Raspberry Pi OS - COMPLETE dependencies (copy-paste this!)
  sudo apt update
  sudo apt install -y build-essential pkg-config \
    libssl-dev libudev-dev libasound2-dev \
    libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
    libwayland-dev wayland-protocols libxkbcommon-dev \
    libvulkan-dev libfontconfig-dev libfreetype-dev \
    libv4l-dev
  
  # Fedora/RHEL/CentOS
  sudo dnf groupinstall "Development Tools"
  sudo dnf install -y pkg-config openssl-devel systemd-devel alsa-lib-devel \
    libX11-devel libXrandr-devel libXi-devel libXcursor-devel libXinerama-devel \
    wayland-devel wayland-protocols-devel libxkbcommon-devel \
    vulkan-devel fontconfig-devel freetype-devel \
    libv4l-devel
  
  # Arch Linux
  sudo pacman -S base-devel pkg-config openssl systemd alsa-lib \
    libx11 libxrandr libxi libxcursor libxinerama \
    wayland wayland-protocols libxkbcommon \
    vulkan-icd-loader fontconfig freetype2 \
    v4l-utils
  

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

What these packages do:

• Core: libssl-dev (networking), libudev-dev (device detection), libasound2-dev (audio)
• Graphics/GUI: X11, Wayland libraries (required for sim2d and monitor)
• Optional: libv4l-dev (camera support), fontconfig (improved text rendering)

Not required:

• Rust (installed in Step 1)
• Git (installed in Step 2)
• Systems programming experience

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/softmata/horus.git
cd horus

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

# 4. Verify it works
horus --help

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

If the help command displays available commands and verify.sh shows green checkmarks, installation is complete. Skip to Next Steps.

What the installer does:

• Builds the horus CLI tool
• Installs five 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_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. No prior Rust experience is required; HORUS also supports Python for application development.

On Linux (or WSL/Docker):

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.

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

# Fedora
sudo dnf install git

# Arch Linux
sudo pacman -S git

Step 3: Clone HORUS

Download the HORUS source code:

git clone https://github.com/softmata/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

The output displays progress with colored indicators. Green checkmarks indicate successful steps.

Step 5: Verify Installation

Test that the horus command works:

horus --help

You should see a list of available commands like new, run, monitor, 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, ALSA, X11, Wayland, etc.)
• [+] Graphics libraries (required for sim2d and monitor)
• [+] HORUS binary and installation path
• [+] Core libraries in ~/.horus/cache/
• [+] All subcommands (new, run, monitor, pkg, env, auth, sim)
• [+] Build verification (cargo check with 0 warnings)
• [+] Debug binary functionality
• [+] Optional features (Python bindings, camera support)
• [+] Platform-specific packages (Raspberry Pi GPIO, Jetson CUDA)
• [+] 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: --help
   All subcommands: Accessible
   Build: cargo check passes (0 warnings)
   Binary: Debug build functional

Summary:
   All checks passed.
   HORUS is properly installed and ready to use.

If there are issues:

• [!] Warnings - Minor issues, HORUS will work but review suggestions
• Errors - Critical problems, see Manual Recovery

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

• Update HORUS (git pull && ./install.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 installed successfully')"

Manual installation (if automatic installation was skipped):

# 1. Install maturin (Python build tool)
# Option A: Via Cargo (recommended for Ubuntu 24.04+)
cargo install maturin

# Option B: Via pip (if not blocked by PEP 668)
# 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.

Platform-Specific Notes

Linux (Ubuntu/Debian)

Linux installation is straightforward. If build errors occur, install all required packages:

sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

Linux (Fedora/RHEL)

sudo dnf groupinstall "Development Tools"
sudo dnf install -y pkg-config openssl-devel systemd-devel alsa-lib-devel \
  libX11-devel libXrandr-devel libXi-devel libXcursor-devel libXinerama-devel \
  wayland-devel wayland-protocols-devel libxkbcommon-devel \
  vulkan-devel fontconfig-devel freetype-devel \
  libv4l-devel

Raspberry Pi

HORUS fully supports Raspberry Pi (tested on Pi 3, 4, and 5). Install Ubuntu Server or Raspberry Pi OS, then:

# Install all dependencies
sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

# Raspberry Pi specific packages (GPIO, I2C, SPI support)
sudo apt install -y libraspberrypi-dev i2c-tools python3-smbus

# Enable I2C and SPI (required for sensors)
sudo raspi-config
# Navigate to: Interface Options → I2C → Enable
# Navigate to: Interface Options → SPI → Enable

Performance tips:

• Use 64-bit OS for better performance
• Compile with --release flag (much faster than debug)
• Allocate more RAM to GPU if using camera nodes (in /boot/config.txt)

NVIDIA Jetson Nano

HORUS supports Jetson Nano with GPU acceleration for vision tasks:

# Install all dependencies
sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

# Jetson specific packages (GPU acceleration)
sudo apt install -y nvidia-jetpack

# Verify CUDA is installed
nvcc --version

GPU acceleration:

• HORUS can leverage CUDA for vision processing nodes
• Ensure JetPack is installed for full GPU support
• Camera nodes automatically use hardware H.264 encoding

Hardware Driver Support (Optional)

HORUS includes hardware drivers for real robotics hardware. These are completely optional - the default installation does NOT require any hardware packages or drivers.

Key points:

• Default ./install.sh works without any hardware packages
• Nodes automatically use simulation mode without hardware
• Hardware features are only compiled when explicitly enabled
• You can install HORUS on your laptop and deploy to hardware later

When you need hardware packages:

• Only when you want to enable hardware features with --features="can-hardware" etc.
• Only for production deployment on actual robots
• Never needed for development, testing, or simulation

Available Hardware Drivers

Installing Hardware Driver Packages

For Raspberry Pi GPIO/I2C/SPI/PWM:

sudo apt install -y libraspberrypi-dev i2c-tools python3-smbus

# Enable hardware interfaces
sudo raspi-config
# Navigate to: Interface Options → I2C → Enable
# Navigate to: Interface Options → SPI → Enable
# Navigate to: Interface Options → Serial Port → Enable

For CAN bus debugging tools:

sudo apt install -y can-utils

# Setup virtual CAN for testing
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

# Test CAN tools
cansend vcan0 123#DEADBEEF
candump vcan0

For Intel RealSense depth cameras:

# Add Intel RealSense repository
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key F6E65AC044F831AC80A06380C8B3A55A6F3EFCDE
sudo add-apt-repository "deb https://librealsense.intel.com/Debian/apt-repo $(lsb_release -cs) main" -u

# Install RealSense SDK
sudo apt install -y librealsense2-dev librealsense2-utils

# Test camera
realsense-viewer

Workflow: Development to Hardware Deployment

Development (on your laptop):

# 1. Install HORUS normally (no hardware packages needed)
./install.sh

# 2. Create and run your project
horus new my_robot
cd my_robot
horus run   # Runs in simulation mode

Deployment (on the robot):

# 1. Install system packages on the robot
sudo apt install libraspberrypi-dev i2c-tools can-utils

# 2. Enable hardware features and run
horus run --enable gpio,i2c --release

Or configure in horus.yaml:

enable:
  - gpio
  - i2c

Then run:

horus run --release

For cargo projects (not using HORUS CLI):

cargo build --release --features="gpio-hardware,i2c-hardware"

Important: You enable hardware features in your project, not in the global HORUS installation. Cargo will automatically recompile horus_library with the right features when building your project.

Available features:

• can-hardware - SocketCAN support for CAN bus
• spi-hardware - spidev support for SPI devices
• i2c-hardware - i2cdev support for I2C devices
• serial-hardware - serialport support for serial devices
• gpio-hardware - GPIO/PWM support (Raspberry Pi)
• motor-hardware - Alias for serial-hardware (Dynamixel, Roboclaw)
• all-hardware - Enable all hardware features

How hardware fallback works:

1. Node attempts to initialize hardware (e.g., open /dev/spidev0.0)
2. If hardware is unavailable, node logs a warning and uses simulation
3. Status messages show (HW) for hardware mode, (SIM) for simulation
4. This allows development on laptops and deployment on hardware without code changes

Supported Hardware Nodes

Communication Buses:

• CanBusNode - CAN bus (SocketCAN)
• SpiBusNode - SPI bus (spidev)
• I2cBusNode - I2C bus (i2cdev)

Motors & Actuators:

• DynamixelNode - Dynamixel smart servos (serial)
• RoboclawMotorNode - Roboclaw motor controllers (serial)
• StepperMotorNode - Stepper motors (GPIO)
• BldcMotorNode - BLDC motors / ESCs (PWM)

Sensors:

• UltrasonicNode - Ultrasonic distance sensors (GPIO)
• BatteryMonitorNode - INA219/INA226 power monitors (I2C)
• ForceTorqueSensorNode - F/T sensors (Modbus TCP, serial)
• DepthCameraNode - RealSense cameras (librealsense2)

See the Built-in Nodes documentation for detailed usage examples.

Windows (Native)

HORUS has native Windows support using %TEMP%\horus\ for shared memory:

# 1. Install Rust (using rustup-init.exe from rustup.rs)
# Download and run: https://win.rustup.rs/x86_64

# 2. Clone HORUS (in PowerShell or Git Bash)
git clone https://github.com/softmata/horus.git
cd horus

# 3. Run the install script (Git Bash or WSL recommended)
./install.sh

# 4. Verify installation
horus --help

Note: On Windows, we recommend using Git Bash or WSL to run the install script. Alternatively, you can build manually with cargo build --release and copy the binary to your PATH.

Windows shared memory:

• Uses %TEMP%\horus\ (typically C:\Users\<user>\AppData\Local\Temp\horus\)
• Automatically created on first run
• Cross-process communication works natively

Alternative: WSL 2 (if you prefer Linux environment)

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

macOS (Native)

HORUS has native macOS support using /tmp/horus/ for shared memory:

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

# 2. Install Xcode Command Line Tools (if not already installed)
xcode-select --install

# 3. Clone and build HORUS
git clone https://github.com/softmata/horus.git
cd horus
./install.sh

# 4. Verify installation
horus --help

macOS shared memory:

• Uses /tmp/horus/ (tmpfs-backed, fast)
• Automatically created on first run
• Same API as Linux - no code changes needed

Alternative options (if native doesn't work for your use case):

• Docker - Run HORUS in a Linux container
• VMware/Parallels - Full Linux VM
• Cloud Linux - Remote development on AWS/DigitalOcean

Understanding Shared Memory

HORUS uses platform-specific shared memory for ultra-fast communication between components:

Check available space:

# Linux
df -h /dev/shm

# macOS
df -h /tmp

# Windows (PowerShell)
Get-PSDrive -Name $env:TEMP.Substring(0,1)

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

If you need more space (Linux only):

# 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:

# Navigate to HORUS directory
cd horus

# Pull latest changes and reinstall
git pull
./install.sh

To preview changes before updating:

git fetch
git log HEAD..@{u}  # See what's new
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 (platform-specific paths)
5. Leave project-local .horus/ directories untouched

Manual uninstall (if needed):

Linux/macOS:

# 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 (optional - HORUS auto-cleans sessions)
# Linux:
rm -rf /dev/shm/horus/
# macOS:
rm -rf /tmp/horus/

Windows (PowerShell):

# Remove CLI tool
cargo uninstall horus

# Remove global cache and config
Remove-Item -Recurse -Force "$env:USERPROFILE\.horus"

# Remove source code
Remove-Item -Recurse -Force "$env:USERPROFILE\horus"  # or wherever you cloned it

# Clean up shared memory (optional - HORUS auto-cleans sessions)
Remove-Item -Recurse -Force "$env:TEMP\horus"

Troubleshooting

Having installation issues? Try manual recovery:

# Navigate to HORUS source directory
cd /path/to/horus

# Clean and reinstall
cargo clean
rm -rf ~/.horus/cache
./install.sh

# Verify installation
./verify.sh

Common issues:

• Missing packages: Install all required system dependencies (see above)
• Raspberry Pi: Ensure GPIO/I2C packages are installed
• Jetson Nano: Ensure CUDA/JetPack packages are installed

See the Troubleshooting & Maintenance Guide for:

• Common installation errors and detailed fixes
• System dependency issues
• Verify script (verify.sh)
• Platform-specific problems
• 15+ solved issues with step-by-step solutions

Next Steps

With HORUS installed, proceed to one of the following:

1. Quick Start Tutorial - Build your first HORUS application
2. CLI Reference - Complete command documentation
3. Examples - Sample HORUS applications

Recommended: Start with the Quick Start Tutorial.