macOS Quickstart Guide

Table of Contents

• System Requirements

• Method 1: conda Environment Setup (Preferred)

• Method 2: vcpkg Package Manager

• Method 3: Manual Dependency Management (Advanced Users)

---

System Requirements

• C++ Compiler: C++20 compatible

  • Xcode 12+ or Clang 10+

• Version Control: Git (recent version)

• Build System: CMake 3.16+

• Configuration Tool: pkg-config

Installing Base Dependencies

For systems lacking these tools:

# Install Xcode Command Line Tools (includes git, clang):
xcode-select --install

# Install CMake and pkg-config via Homebrew:
brew install cmake pkg-config

Alternative for conda Users

When using the conda approach below, you may install prerequisites within your conda environment instead of system-wide:

conda install -c conda-forge cmake git pkg-config cxx-compiler make

This eliminates the need for sudo privileges while still providing the necessary build tools.

---

Method 1: conda Environment Setup (Preferred)

This approach leverages conda for streamlined dependency management and is our top recommendation. Ensure your system requirements are met first.

Step 1: conda Installation

If conda isn’t already available:

For Apple Silicon:

cd ~
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh"

chmod +x Miniforge3-MacOSX-arm64.sh
./Miniforge3-MacOSX-arm64.sh

For Intel (x86):

cd ~
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh"

chmod +x Miniforge3-MacOSX-x86_64.sh
./Miniforge3-MacOSX-x86_64.sh

Complete the installation prompts and verify conda activation by checking for (base) in your terminal prompt. If it is not activated, you may need to run source ~/miniforge3/bin/activate.

Step 2: Environment Creation

conda env create -f packaging/environment.yml
conda activate huira_env

Step 3: Compilation Process

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/conda-toolchain.cmake -DCMAKE_BUILD_TYPE=Release ../
cmake --build . -j

Step 4: Environment Installation (Optional)

After successful compilation, integrate Huira into your conda environment:

cmake --install .

---

Method 2: vcpkg Package Manager

vcpkg provides cross-platform package management through source compilation. Initial builds may take considerable time due to source-based dependency building. Verify system requirements before proceeding.

vcpkg Configuration:

git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
~/vcpkg/vcpkg integrate install

Compilation Steps:

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=~/vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release ../
cmake --build . -j

---

Method 3: Manual Dependency Management (Advanced Users)

This approach requires manual installation of all dependencies through system package managers or source compilation. Warning: This method is unsupported and may encounter compatibility issues with system-available library versions.

Required Dependencies

Package	Version Requirement	Purpose
assimp	>=5.2,<6.0	3D asset importing
catch2	>=3.8.0	Unit testing suite (when HUIRA_TESTS=ON)
cfitsio	>=3.49	FITS file handling
cspice	=67	NASA SPICE toolkit
embree3	>=3.13,<4.0	Ray intersection kernels
fftw	>=3.3.10,<4.0	Fourier transform operations
gdal	>=3.10,<4.0	Geographic data processing
glm	>=1.0.1	Mathematical operations
libtiff	>=4.7.0	TIFF image processing
tbb-devel	>=2021.0	Threading Building Blocks

Build Process

Once dependencies are satisfied, execute from the repository root:

mkdir build
cd build
cmake ../ -DCMAKE_BUILD_TYPE=Release
cmake --build . -j