Installation Guide¶

This guide covers building JaguarEngine from source on various platforms.

System Requirements¶

Minimum Requirements¶

Component	Requirement
CPU	x86_64 or ARM64 processor
RAM	4 GB (8 GB recommended for development)
Disk	1 GB free space
OS	Linux, macOS 12+, Windows 10+

Compiler Requirements¶

JaguarEngine requires a C++20 compatible compiler:

Compiler	Minimum Version
GCC	11.0+
Clang	14.0+
AppleClang	15.0+
MSVC	Visual Studio 2022 (17.0+)

Build Tools¶

CMake: 3.25 or later
Make/Ninja: Any recent version

Dependencies¶

Required (Auto-fetched)¶

These dependencies are automatically downloaded by CMake if not found on your system:

Library	Version	Purpose
Eigen3	3.4.0	Linear algebra, matrix operations
pugixml	1.14	XML configuration parsing
GoogleTest	1.14.0	Unit testing framework
Google Benchmark	1.8.3	Performance benchmarking

Optional Dependencies¶

Library	Version	Purpose	CMake Option
GDAL	3.0+	Geospatial terrain loading	Auto-detected
pybind11	2.11+	Python bindings	`JAGUAR_BUILD_PYTHON`
sol2	3.3+	Lua bindings	`JAGUAR_BUILD_LUA`
OpenDIS	-	DIS protocol	`JAGUAR_ENABLE_DIS`
HLA RTI	-	HLA protocol	`JAGUAR_ENABLE_HLA`

Quick Installation¶

Linux / macOS¶

# Clone repository
git clone https://github.com/jaguarcode/JaguarEngine.git
cd JaguarEngine

# Create build directory
mkdir build && cd build

# Configure (dependencies auto-fetched)
cmake ..

# Build (use all available cores)
make -j$(nproc)

# Run tests to verify installation
./jaguar_unit_tests

Windows (Visual Studio)¶

# Clone repository
git clone https://github.com/jaguarcode/JaguarEngine.git
cd JaguarEngine

# Create build directory
mkdir build
cd build

# Configure for Visual Studio 2022
cmake .. -G "Visual Studio 17 2022" -A x64

# Build
cmake --build . --config Release

# Run tests
.\Release\jaguar_unit_tests.exe

Platform-Specific Instructions¶

Ubuntu / Debian¶

# Install build tools
sudo apt update
sudo apt install -y build-essential cmake git

# Optional: Install GDAL for terrain support
sudo apt install -y libgdal-dev

# Optional: Install Python development for bindings
sudo apt install -y python3-dev python3-pip

# Build
cd JaguarEngine
mkdir build && cd build
cmake ..
make -j$(nproc)

Fedora / RHEL¶

# Install build tools
sudo dnf install -y gcc-c++ cmake git

# Optional: Install GDAL
sudo dnf install -y gdal-devel

# Build
cd JaguarEngine
mkdir build && cd build
cmake ..
make -j$(nproc)

macOS¶

# Install Xcode Command Line Tools
xcode-select --install

# Install CMake via Homebrew
brew install cmake

# Optional: Install GDAL
brew install gdal

# Build
cd JaguarEngine
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

Windows¶

Install Visual Studio 2022 with the C++ Desktop Development workload
Install CMake (add to PATH)
Install Git

# From Developer PowerShell for VS 2022
cd JaguarEngine
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release --parallel

Build Options¶

CMake Configuration Options¶

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DJAGUAR_BUILD_TESTS=ON \
    -DJAGUAR_BUILD_BENCHMARKS=ON \
    -DJAGUAR_BUILD_EXAMPLES=ON \
    -DJAGUAR_BUILD_PYTHON=OFF \
    -DJAGUAR_BUILD_LUA=OFF \
    -DJAGUAR_ENABLE_DIS=OFF \
    -DJAGUAR_ENABLE_HLA=OFF \
    -DJAGUAR_ENABLE_SIMD=ON

Build Types¶

Build Type	Description	Use Case
`Debug`	No optimization, full debug symbols	Development, debugging
`Release`	Full optimization (-O3)	Production, benchmarking
`RelWithDebInfo`	Optimization with debug info	Profiling
`MinSizeRel`	Optimize for size	Embedded systems

Option Reference¶

Option	Default	Description
`JAGUAR_BUILD_TESTS`	ON	Build GoogleTest-based unit tests
`JAGUAR_BUILD_BENCHMARKS`	ON	Build Google Benchmark suite
`JAGUAR_BUILD_EXAMPLES`	ON	Build example applications
`JAGUAR_BUILD_PYTHON`	OFF	Build pybind11 Python module
`JAGUAR_BUILD_LUA`	OFF	Build sol2 Lua bindings
`JAGUAR_ENABLE_DIS`	OFF	Enable DIS network protocol
`JAGUAR_ENABLE_HLA`	OFF	Enable HLA federation
`JAGUAR_ENABLE_SIMD`	ON	Enable AVX2/FMA optimizations
`JAGUAR_ENABLE_GPU`	ON	Enable GPU compute acceleration
`JAGUAR_ENABLE_CUDA`	OFF	Enable NVIDIA CUDA backend
`JAGUAR_ENABLE_OPENCL`	OFF	Enable OpenCL backend
`JAGUAR_ENABLE_METAL`	OFF	Enable Metal backend (macOS)
`JAGUAR_ENABLE_XR`	ON	Enable VR/AR (XR) support
`JAGUAR_ENABLE_OPENXR`	OFF	Enable OpenXR runtime
`JAGUAR_ENABLE_CLOUD`	ON	Enable distributed simulation
`JAGUAR_ENABLE_THREAD`	ON	Enable Digital Thread support
`JAGUAR_ENABLE_ML`	ON	Enable Machine Learning support

Phase 7 Advanced Features¶

JaguarEngine v0.5.0 includes enterprise-grade advanced capabilities. Enable these features based on your requirements:

GPU Acceleration¶

# Enable CUDA (NVIDIA GPUs)
cmake .. -DJAGUAR_ENABLE_CUDA=ON

# Enable OpenCL (Cross-platform)
cmake .. -DJAGUAR_ENABLE_OPENCL=ON

# Enable Metal (macOS)
cmake .. -DJAGUAR_ENABLE_METAL=ON

Extended Reality (VR/AR)¶

# Enable OpenXR runtime
cmake .. -DJAGUAR_ENABLE_XR=ON -DJAGUAR_ENABLE_OPENXR=ON

Requires OpenXR runtime installed on your system.

Cloud/Distributed Simulation¶

# Enable cloud burst scaling
cmake .. -DJAGUAR_ENABLE_CLOUD=ON

Machine Learning¶

# Enable ML capabilities
cmake .. -DJAGUAR_ENABLE_ML=ON

Requires ONNX Runtime for neural network inference.

Installing JaguarEngine¶

System-wide Installation¶

cd build
sudo cmake --install . --prefix /usr/local

Custom Installation Path¶

cmake --install . --prefix ~/local/jaguar

Using in Your CMake Project¶

After installation, use JaguarEngine in your CMake projects:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.25)
project(MySimulation)

find_package(Jaguar REQUIRED)

add_executable(my_simulation main.cpp)
target_link_libraries(my_simulation PRIVATE Jaguar::jaguar)

Verifying Installation¶

Run Unit Tests¶

cd build
./jaguar_unit_tests

Expected output:

[==========] Running 237 tests from 41 test suites.
...
[  PASSED  ] 237 tests.

Run Examples¶

# Simple flight simulation
./example_simple_flight

# Multi-domain simulation
./example_multi_domain

Check Build Configuration¶

cmake -L ..   # List all options
cmake -LA ..  # List all options including advanced

Troubleshooting¶

Common Issues¶

Eigen3 Not Found¶

CMake Warning: Eigen3 not found, will use FetchContent

Solution: This is normal behavior. Eigen3 is automatically downloaded if not installed system-wide.

GDAL Not Found¶

CMake Warning: GDAL not found. Terrain features will be limited.

Solution: Install GDAL if you need terrain loading:

Ubuntu: sudo apt install libgdal-dev
macOS: brew install gdal
Windows: Use OSGeo4W installer

Compiler Too Old¶

error: 'span' is not a member of 'std'

Solution: Upgrade to a C++20 compatible compiler:

GCC 11+ (Ubuntu 22.04+ default)
Clang 14+
MSVC 2022

Build Fails on ARM Mac (Rosetta)¶

error: -march=native requires native target

Solution: The build system automatically detects Rosetta and disables native optimizations. Ensure you're using the latest CMakeLists.txt.

Getting Help¶

Check existing GitHub Issues
Search the documentation
Open a new issue with:
OS and version
Compiler version (g++ --version)
CMake version (cmake --version)
Full error output

Next Steps¶

Quick Start Tutorial - Your first simulation
Examples Guide - Code examples for all domains
API Reference - Complete API documentation