Development Environment Setup

Orbitron supports multiple development environment options. Choose the one that best fits your workflow:

2.2 System Packages (Native Development)

Best for: Experienced developers, GUI development, fast iteration

Why use system packages: - ✅ Fast - no container overhead - ✅ Native tooling - direct access to system tools - ✅ GPU access - direct access to GPU for GUI development - ✅ Familiar - standard Rust development workflow

Prerequisites: - Rust toolchain (install via rustup) - System package manager (apt, brew, vcpkg, etc.)

Setup by Platform:

Linux (Debian/Ubuntu):

# Install dependencies
./scripts/install-deps-linux.sh

# Set environment variables
export HDF5_DIR=/usr
export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig

# Build
cargo build --workspace

macOS:

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
./scripts/install-deps-macos.sh

# Set environment variables (add to ~/.zshrc or ~/.bash_profile)
export HDF5_DIR=$(brew --prefix hdf5)
export PKG_CONFIG_PATH="$HDF5_DIR/lib/pkgconfig"
export DYLD_LIBRARY_PATH="$HDF5_DIR/lib:$DYLD_LIBRARY_PATH"

# Build
cargo build --workspace

Windows:

# Prereqs: Visual Studio Build Tools + "Desktop development with C++"
# (MSVC v143 + Windows SDK). Use VS Installer -> Modify -> select workload.

# Option 1: Conda (matches CI)
# 1. Install Miniconda/Anaconda.
# 2. Create env: conda env create -f environment.yml
# 3. Activate: conda activate orbitron-dev
# 4. Point HDF5 to conda (needed for hdf5-sys):
$env:HDF5_DIR = "$env:CONDA_PREFIX\Library"
$env:HDF5_ROOT = "$env:CONDA_PREFIX\Library"
$env:PKG_CONFIG_PATH = "$env:CONDA_PREFIX\Library\lib\pkgconfig"
$env:PATH = "$env:CONDA_PREFIX\Library\bin;$env:PATH"

# Build
cargo build --workspace

# Package like CI (optional)
New-Item -ItemType Directory -Path dist -Force | Out-Null
Copy-Item target\release\orbitron-viewer.exe dist\
Copy-Item target\release\orbitron.exe dist\
Copy-Item target\release\orbitron-tui.exe dist\
$condaBin = Join-Path $env:CONDA_PREFIX "Library\bin"
$dllPatterns = @(
  "hdf5*.dll","libhdf5*.dll","szip*.dll","zlib*.dll","libaec*.dll",
  "libcrypto-*.dll","libssl-*.dll","libcurl-*.dll","libcurl.dll",
  "libssh2.dll"
)
foreach ($pattern in $dllPatterns) {
  Get-ChildItem -Path $condaBin -Filter $pattern -ErrorAction SilentlyContinue | `
    Copy-Item -Destination dist -Force -ErrorAction SilentlyContinue
}
New-Item -ItemType Directory -Path dist\packages -Force | Out-Null
Compress-Archive -Path dist\* -DestinationPath dist\packages\orbitron-windows.zip -Force

# Option 2: Use vcpkg (recommended for system installs)
# 1. Install vcpkg: https://github.com/Microsoft/vcpkg
# 2. Install HDF5: vcpkg install hdf5:x64-windows
# 3. Set environment:
#    set VCPKG_ROOT=<path-to-vcpkg>
#    set HDF5_DIR=%VCPKG_ROOT%\installed\x64-windows

# Option 3: Use Docker (see §2.1)
# Option 4: See scripts/install-deps-windows.sh for more options

Troubleshooting:

  • HDF5 not found: Ensure HDF5_DIR points to the HDF5 installation directory
  • pkg-config errors: Set PKG_CONFIG_PATH to include HDF5’s pkgconfig directory
  • macOS library errors: Add HDF5 lib directory to DYLD_LIBRARY_PATH

2.3 Conda Environment (Optional)

Best for: Users already using conda, HPC environments, Python bridge development

Why use conda: - ✅ Isolated environment (similar to Docker) - ✅ Good for scientific computing workflows - ✅ Useful for Python bridge development - ✅ Common in HPC environments - ✅ Environment variables automatically set via environment.yml

Note: This is optional. System packages or Docker are recommended for most users.

Setup:

Option 1: Using setup script (recommended):

# Creates environment from environment.yml and sets up activation scripts
./scripts/setup-conda-env.sh

# Activate the environment
conda activate orbitron-dev

# Environment variables (HDF5_DIR, PKG_CONFIG_PATH, DYLD_LIBRARY_PATH) are automatically set!
# Activation scripts properly expand ${CONDA_PREFIX} at activation time

# Build
cargo build --workspace

Option 2: Manual setup:

# Create environment from environment.yml
conda env create -f environment.yml

# Activate environment
conda activate orbitron-dev

# Set up activation scripts (one-time setup)
mkdir -p "${CONDA_PREFIX}/etc/conda/activate.d"
mkdir -p "${CONDA_PREFIX}/etc/conda/deactivate.d"
cp scripts/conda-activate.sh "${CONDA_PREFIX}/etc/conda/activate.d/orbitron-env.sh"
cp scripts/conda-deactivate.sh "${CONDA_PREFIX}/etc/conda/deactivate.d/orbitron-env.sh"
chmod +x "${CONDA_PREFIX}/etc/conda/activate.d/orbitron-env.sh"
chmod +x "${CONDA_PREFIX}/etc/conda/deactivate.d/orbitron-env.sh"

# Deactivate and reactivate to load environment variables
conda deactivate
conda activate orbitron-dev

# Build
cargo build --workspace

Note: - Activation scripts reliably expand ${CONDA_PREFIX} at activation time (unlike conda’s variables section which treats it as a literal) - Environment variables are automatically set when you activate the environment - no manual exports needed! - The environment.yml file defines packages; activation scripts handle environment variables

Customizing Environment Name:

ORBITRON_CONDA_ENV=myenv ./scripts/setup-conda-env.sh

Files: - scripts/setup-conda-env.sh - Automated conda environment setup - environment.yml - Conda environment specification (if you want to create one)

Troubleshooting:

  • Conda not found: Install Miniconda or Anaconda first
  • Environment already exists: The script will prompt to recreate it
  • Path issues: Always use $CONDA_PREFIX, never hardcoded paths