Troubleshooting & Maintenance

HORUS includes utility scripts to help you update, recover from broken installations, and verify your setup.

Quick Reference

Script	Use When	What It Does
`./update.sh`	Update to latest version	Smart incremental update (auto git pull)
`./verify.sh`	Check installation health	Diagnose issues, verify setup
`./recovery_install.sh`	Build errors, corrupted cache	Nuclear option: fresh rebuild
`./install.sh`	First time installation	Full installation from source
`./uninstall.sh`	Remove HORUS	Complete removal

update.sh - Smart Updates

Use when: You want to update to the latest version

Quick Usage

cd /path/to/HORUS
./update.sh  # Automatically pulls latest changes

What It Does

Safety checks: Detects uncommitted changes, offers to stash
Git update: Shows what changed, pulls latest commits
Smart detection: Only rebuilds what's necessary
Dependency update: Updates Cargo.toml if needed
Verification: Quick smoke test after update

Example Session

$ ./update.sh
 HORUS Update Script

 Current version: 0.1.0

 Fetching latest changes from remote...
 Updates available on main

Recent changes:
  * a1b2c3d Fix edge detection bug
  * d4e5f6g Add ONNX runtime support
  * g7h8i9j Update dependencies

Pull and update? [Y/n]: y

 Pulling latest changes...
 Updated to latest commit

 Analyzing changes...
 Cargo.toml files changed - dependencies may have updated
 Rust source files changed

 Updating dependencies...
 Dependencies updated

 Rebuilding HORUS (release mode)...
   Compiling horus_core v0.1.1
   Compiling horus v0.1.1
 Build completed

 Installing updated binary...
 Binary installed to ~/.cargo/bin/horus

 Updating library cache...
 Libraries updated

 Verifying update...
 New version: 0.1.1
 Smoke test passed

 Update complete!

Version: 0.1.0  0.1.1

Options

Handle uncommitted changes:

  Warning: You have uncommitted changes

 M horus_core/src/scheduler.rs
 M docs/readme.md

? Stash changes before updating? [y/N]: y
 Changes stashed

Rebuild even if up-to-date:

 Already up to date

? Rebuild anyway? [y/N]: y

Troubleshooting update.sh

Error: Not in a git repository

Make sure you're in the HORUS repository root
Run: git status to verify

Build failed during update

Try: ./recovery_install.sh for fresh rebuild
Check error messages above
Verify dependencies: ./verify.sh

verify.sh - Installation Health Check

Use when: Diagnosing issues, checking if installation is correct

Quick Usage

./verify.sh

What It Checks

System Requirements
- Rust version (>= 1.70)
- Cargo installation
- C compiler
- pkg-config
- System libraries (OpenSSL, udev)
HORUS Installation
- Binary location and version
- PATH configuration
- Core libraries
- Optional components (Python/C bindings)
Functionality Tests
- Commands work (--version, --help)
- All subcommands accessible (new, run, dashboard, pkg, env, auth, version)
- Build verification (when run in HORUS repo):
  - cargo check passes without errors
  - Zero warnings in codebase
  - Debug binary is functional
Disk Usage
- Cache sizes
- Installation footprint

Example Output


   HORUS Installation Verification


System Requirements:

   Rust: 1.75.0 (>= 1.70 required)
   Cargo: 1.75.0
   C compiler: GCC
   pkg-config: 0.29.2

System Libraries:

   OpenSSL: 3.0.2
   udev: Not found (optional for some features)

HORUS Installation:

   Binary: v0.1.0 at ~/.cargo/bin/horus
   In PATH: Yes (correct binary)

Core Libraries:

   Installed version: 0.1.0
   Main library: v0.1.0
   Runtime core: v0.1.0
   Proc macros: v0.1.0
   Standard library: v0.1.0
   C bindings: Not installed (optional)
   Python bindings: Not installed (optional)

Functionality Tests:

   Command: --version
   Command: --help
   All subcommands: Accessible

   Running build verification...
   Build: cargo check passes (0 warnings)
   Binary: Debug build functional

Disk Usage:

   ~/.horus: 45M
   Library cache: 42M
   Cargo cache: 2.3G


Summary:

   Perfect! Everything looks good.

  HORUS is properly installed and ready to use.

Exit Codes

Useful for CI/CD:

./verify.sh
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
    echo "All good!"
elif [ $EXIT_CODE -eq 1 ]; then
    echo "Warnings found"
else
    echo "Errors found"
fi

0 = Perfect, no issues
1 = Warnings (minor issues)
2 = Errors (installation broken)

Common Warnings

Binary not in PATH:

 'horus' command not found in PATH
  Add to shell profile (~/.bashrc, ~/.zshrc, etc.):
  export PATH="$HOME/.cargo/bin:$PATH"

Old Rust version:

 Rust: 1.65.0 (< 1.70, please update)
  Update with: rustup update

Missing optional libraries:

 udev: Not found (optional for some features)
  Ubuntu/Debian: sudo apt install libudev-dev
  Fedora: sudo dnf install systemd-devel

recovery_install.sh - Nuclear Recovery

Use when: Build errors, corrupted cache, installation broken

Quick Usage

./recovery_install.sh

What It Does

Phase 1: Comprehensive Diagnostics

Checks 30+ system requirements
Detects missing dependencies
Finds version conflicts
Reports all issues clearly

Phase 2: Deep Cleanup

Removes all build artifacts (target/)
Cleans HORUS from cargo cache
Removes old binaries
Optionally cleans ~/.horus/cache

Phase 3: Fresh Installation

Runs install.sh from scratch
Clean build in release mode
Fresh library installation

Phase 4: Verification

Tests binary works
Verifies all libraries installed
Checks PATH configuration

Example Session

$ ./recovery_install.sh
 HORUS Recovery Installation Script


This script will:
  • Detect system dependencies and issues
  • Clean all build artifacts and caches
  • Fresh installation from scratch
  • Comprehensive verification

? Continue with recovery installation? [y/N]: y

 PHASE 1: System Diagnostics 

 Checking Rust toolchain...
   Rust: 1.75.0
   Cargo: 1.75.0

 Checking C compiler...
   C compiler: gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0

 Checking system dependencies...
   pkg-config: 0.29.2
   libopenssl: 3.0.2
   libudev: not found (optional)

 Checking for existing HORUS installations...
   Found existing binary: 0.1.0
   Multiple 'horus' commands found in PATH
      - /home/user/.cargo/bin/horus
      - /usr/local/bin/horus

 Diagnostic Summary 
  Errors:   0
  Warnings: 3

  Warnings found
You can continue, but some features may not work.

? Continue anyway? [y/N]: y

 PHASE 2: Cleanup 

 Cleaning build artifacts...
   Removing target/ (1.2G)...
   Build artifacts removed

 Cleaning HORUS from cargo cache...
   Cargo cache cleaned

? Remove ~/.horus/cache (installed libraries)? [Y/n]: y
   HORUS cache removed

? Remove ~/.horus/config (user settings)? [y/N]: n
   Keeping user config

   Old binary removed

 Cleanup complete

 PHASE 3: Fresh Installation 

 Running install.sh...

[... install.sh output ...]

 PHASE 4: Verification 

 Testing HORUS binary...
   Binary works: v0.1.0

 Testing basic commands...
   --help works

 Checking PATH...
   'horus' found in PATH
       ~/.cargo/bin/horus

 Checking installed libraries...
   Installed version: 0.1.0
   horus installed
   horus_core installed
   horus_macros installed
   horus_library installed

 Recovery installation successful!

Next steps:
  1. Test creating a project:
     horus new test_project

  2. Run it:
     cd test_project && horus run

When to Use Recovery Install

Symptoms requiring recovery:

Build fails:
```
error: could not compile `horus_core`
```

Corrupted cache:

error: failed to load source for dependency `horus_core`

Binary doesn't work:
```
$ horus --version
Segmentation fault
```

Version mismatches:

error: the package `horus` depends on `horus_core 0.1.0`,
but `horus_core 0.1.1` is installed

Broken after system updates:
- Rust updated
- System libraries changed
- GCC/Clang updated

What Gets Removed

Always removed:

target/ directory (build artifacts)
Old ~/.cargo/bin/horus binary
HORUS entries in ~/.cargo/registry

Ask before removing:

~/.horus/cache (installed libraries)
~/.horus/config (user settings)

Never removed:

Project-local .horus/ directories
~/.horus/credentials (registry auth)
Your source code

Common Issues & Solutions

Installation Issues

Problem: "Rust not installed"

$ ./install.sh
 Error: Rust is not installed

Solution:

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

# Then try again
./install.sh

Problem: "C compiler not found"

Solution:

# Ubuntu/Debian
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

# macOS
xcode-select --install
brew install pkg-config

Problem: Build fails with linker errors

error: linking with `cc` failed: exit status: 1

Solution:

# Install missing system libraries
# Ubuntu/Debian
sudo apt update && sudo apt install \
  build-essential \
  pkg-config \
  libudev-dev \
  libssl-dev \
  libasound2-dev

# Or run recovery
./recovery_install.sh

Update Issues

Problem: "Build failed" during update

Solution:

# Try recovery instead
./recovery_install.sh

Problem: "Already up to date" but binary broken

Solution:

# Force rebuild
./update.sh
# When asked "Rebuild anyway?", answer: y

Runtime Issues

Problem: "horus: command not found"

Solution:

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Then reload shell
source ~/.bashrc  # or restart terminal

# Verify
which horus
horus --version

Problem: Binary exists but doesn't run

$ horus --version
Segmentation fault

Solution:

# Full recovery
./recovery_install.sh

Problem: Version mismatch errors

error: the package `horus` depends on `horus_core 0.1.0`,
but `horus_core 0.1.1` is installed

Solution:

# Recovery will clean mismatched versions
./recovery_install.sh

Problem: "HORUS source directory not found" (Rust projects)

Error: HORUS source directory not found. Please set HORUS_SOURCE environment variable.

Solution:

# Option 1: Set HORUS_SOURCE (recommended for non-standard installations)
export HORUS_SOURCE=/path/to/HORUS
echo 'export HORUS_SOURCE=/path/to/HORUS' >> ~/.bashrc

# Option 2: Install HORUS to a standard location
# The CLI checks these paths automatically:
#   - ~/horus/HORUS
#   - /horus
#   - /opt/horus
#   - /usr/local/horus

# Verify HORUS source is found
horus run --build-only

Why this happens:

horus run needs to find HORUS core libraries for Rust compilation
It auto-detects standard installation paths
For custom installations, set $HORUS_SOURCE

Performance Issues

Problem: Slow builds

Solution:

# Use release mode (optimized)
horus run --release

# Or configure in horus.yaml
mode: release

Problem: Large disk usage

Solution:

# Check usage
./verify.sh

# Clean old cargo cache
cargo clean

# Remove unused dependencies
cargo install cargo-cache
cargo cache --autoclean

Problem: Large .horus/target/ directory (Rust projects)

Why this happens:

Cargo stores build artifacts in .horus/target/
Debug builds are unoptimized and larger
Incremental compilation caches intermediate files

Solution:

# Clean build artifacts in current project
rm -rf .horus/target/

# Or use horus clean flag (next build will be slower)
horus run --clean

# Regular cleanup (if working on multiple projects)
find . -type d -name ".horus" -exec rm -rf {}/target/ \;

# Add to .gitignore (already included in horus new templates)
echo ".horus/target/" >> .gitignore

Disk usage typical sizes:

.horus/Cargo.toml: ~266 bytes
.horus/target/debug/: ~10-100 MB (incremental builds)
.horus/target/release/: ~5-50 MB (optimized, no debug symbols)

Best practices:

.horus/target/ is in .gitignore by default
Clean periodically if disk space is limited
Only .horus/Cargo.toml and .horus/Cargo.lock are needed for rebuild

Best Practices

Regular Maintenance

Weekly (active development):

./update.sh  # Pulls latest and rebuilds

Monthly:

./verify.sh  # Check for warnings

After system updates:

./recovery_install.sh  # If Rust/GCC updated

CI/CD Integration

# In CI pipeline
./verify.sh || ./recovery_install.sh

# Exit codes
if ./verify.sh; then
    echo "Installation OK"
else
    echo "Installation has issues, check logs"
    exit 1
fi

Debugging Workflow

First: Verify installation
```
./verify.sh
```
If warnings: Update
```
./update.sh
```
If errors: Recovery
```
./recovery_install.sh
```

Still broken: Report issue

./verify.sh > diagnostic.txt
# Attach diagnostic.txt to issue report

Getting Help

If you encounter issues:

Run diagnostics:
```
./verify.sh > diagnostic.txt
```
Try recovery:
```
./recovery_install.sh
```
Check common issues (above)
Report the issue:
- Include output from verify.sh
- Describe what you were doing
- System info (OS, Rust version)
- GitHub: https://github.com/your-org/horus/issues

Next Steps

Installation - First-time installation guide
CLI Reference - All horus commands
Examples - Working code examples
Performance - Optimization tips