Build Azahar from Source on macOS (Apple Silicon and Intel)

Building Azahar on macOS requires Xcode Command Line Tools, Homebrew, and CMake 3.25 or later. Azahar supports both Apple Silicon (arm64) and Intel (x86_64) Macs, and the CI pipeline produces a universal binary by combining both architectures using lipo. The minimum supported macOS version is 13.4 (Ventura), and AppleClang 15.0 or later is required.

Install Xcode Command Line Tools

Run the following command in Terminal. A dialog will appear prompting you to install the tools:

xcode-select --install

Once the installation completes, verify that the compiler is available:

clang --version

AppleClang versions earlier than 15.0 will cause a compilation failure due to a known compiler bug. If your version is below 15.0, update Xcode via the Mac App Store before proceeding.

Install Homebrew

If you do not already have Homebrew, install it by running the official install script:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions. On Apple Silicon Macs, Homebrew installs to /opt/homebrew/; on Intel Macs it installs to /usr/local/. Make sure Homebrew’s bin directory is in your PATH.

Install dependencies

Install the required build tools and libraries via Homebrew:

brew install \
  cmake \
  ninja \
  qt6 \
  boost \
  sdl2 \
  openssl \
  zstd \
  libusb \
  speexdsp \
  ccache

Several additional libraries—including dynarmic, fmt, cryptopp, soundtouch, cubeb, openal-soft, glslang, vulkan-headers, and MoltenVK—are bundled as Git submodules or downloaded automatically by CMake during configuration. You do not need to install them separately.

Installing ccache is optional but highly recommended. It dramatically reduces incremental rebuild times.

Clone the repository with submodules

Clone the Azahar repository and initialize all submodules:

git clone --recurse-submodules https://github.com/azahar-emu/azahar.git
cd azahar

If you already cloned without --recurse-submodules, run:

git submodule update --init --recursive

Configure with CMake

Create a build directory and configure the project. CMake will automatically detect your architecture.

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

To target a specific architecture explicitly (useful when building a fat binary), pass CMAKE_OSX_ARCHITECTURES:

# Apple Silicon only
cmake -B build/arm64 -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_OSX_ARCHITECTURES=arm64

# Intel only
cmake -B build/x86_64 -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_OSX_ARCHITECTURES=x86_64

Commonly used CMake options are listed below:

Option	Default	Description
`ENABLE_QT`	`ON`	Build the Qt6 desktop frontend
`ENABLE_VULKAN`	`ON`	Enable the Vulkan renderer (via MoltenVK)
`ENABLE_OPENAL`	`ON`	Enable the OpenAL audio backend
`ENABLE_CUBEB`	`ON`	Enable the cubeb audio backend
`ENABLE_LIBUSB`	`ON`	Enable libusb for GameCube Adapter support
`USE_DISCORD_PRESENCE`	`OFF`	Enable Discord Rich Presence
`ENABLE_QT_TRANSLATION`	`OFF`	Bundle Qt UI translations
`ENABLE_ROOM_STANDALONE`	`ON`	Build the standalone `azahar-room` server

Build

Compile the project:

cmake --build build --config Release

To create a distributable .app bundle with all required frameworks and libraries included, run the bundle target:

cmake --build build --target bundle

The finished app bundle appears at build/bundle/Azahar.app.

Apple Silicon and Intel support

Azahar supports both arm64 and x86_64 natively. If you want to produce a single universal binary that runs on both, build each architecture separately and then merge them using lipo:

# Build arm64
cmake -B build/arm64 -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_OSX_ARCHITECTURES=arm64
cmake --build build/arm64 --target bundle

# Build x86_64
cmake -B build/x86_64 -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_OSX_ARCHITECTURES=x86_64
cmake --build build/x86_64 --target bundle

# Merge the two executables into a universal binary
lipo -create \
    -output build/universal/Azahar.app/Contents/MacOS/azahar \
    build/arm64/bundle/Azahar.app/Contents/MacOS/azahar \
    build/x86_64/bundle/Azahar.app/Contents/MacOS/azahar

After merging, re-sign the app bundle:

codesign --deep -fs - build/universal/Azahar.app

The CI pipeline automates this process using the .ci/macos-universal.sh script, which also merges all bundled .dylib files that do not have conflicting architectures.

Building

Architecture

Contributing

Build Azahar from Source on macOS (Apple Silicon and Intel)

Build docs developers (and LLMs) love

Building

Architecture

Contributing

Documentation Index

Build docs developers (and LLMs) love