macOS C++ Build Guide

Table of Contents

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 (ARM):

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/download/26.3.2-3/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

After successful compilation, integrate Huira into your conda environment:

cmake --install . --prefix "$CONDA_PREFIX"

[!IMPORTANT] To uninstall, you must run cmake --build . --target uninstall from within the same build directory you installed from.

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