Building Hydra

Step-by-step guide to building Hydra from source

Prerequisites

Before building Hydra, ensure you have the following installed on your system:

macOS Requirements

• Xcode (14.0 or later) - Required for Apple development tools and frameworks
• CMake (3.15 or later) - Build system generator
• Ninja - Fast build system (recommended)
• Git - For cloning the repository and submodules

Dependencies

You can install the required dependencies using Homebrew:

brew install cmake ninja sdl3 fmt

Required Dependencies

• SDL3 - For the SDL3 frontend (default on macOS)
• fmt - Formatting library (will be auto-downloaded if not found)

Bundled Dependencies

The following dependencies are included as Git submodules:

• dynarmic - ARM CPU emulator
• cubeb - Cross-platform audio library
• hatch - TOML configuration library
• libyaz0 - Yaz0 compression library
• nx2elf - Nintendo Switch executable converter
• metal-cpp - C++ Metal API wrapper
• stb - Image and font loading libraries

Getting the Source Code

1. Clone the repository

   Clone the Hydra repository from GitHub:

   git clone https://github.com/SamoZ256/hydra.git
   cd hydra
   
2. Initialize submodules

   Download all the required external dependencies:

   git submodule update --init --recursive
   

   This will fetch:

   • dynarmic (ARM CPU emulator)
   • cubeb (audio backend)
   • hatch (configuration library)
   • libyaz0 (compression)
   • nx2elf (executable converter)
   • And other dependencies

Building

Standard Build (SDL3 Frontend)

1. Configure CMake

   Generate build files with Ninja:

   cmake . -B build -G Ninja -DMACOS_BUNDLE=ON
   

   This creates a macOS application bundle with the SDL3 frontend.

2. Build the project

   Compile Hydra using Ninja:

   ninja -C build
   
3. Locate the application

   The macOS app bundle will be created at:

   build/bin/Hydra.app
   

   You can launch it directly or copy it to your Applications folder.

SwiftUI Frontend Build

For a native macOS experience using SwiftUI:

cmake . -B build -G Ninja -DMACOS_BUNDLE=ON -DFRONTEND=SwiftUI
ninja -C build

The SwiftUI frontend requires macOS 15.0 or later, while the SDL3 frontend works with macOS 13.0+.

Build Configurations

Debug Build

Debug builds include additional logging and debugging symbols:

cmake . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DMACOS_BUNDLE=ON
ninja -C build

Debug builds automatically:

• Define HYDRA_DEBUG preprocessor macro
• Include Git commit hash in the version
• Enable additional runtime checks

Release Build

Release builds are optimized for performance:

cmake . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DMACOS_BUNDLE=ON
ninja -C build

Release builds:

• Enable compiler optimizations
• Omit debug symbols
• Skip Git hash in version string

Build Options

CMake Configuration Options

Frontend Selection

# Use SDL3 frontend (default)
-DFRONTEND=SDL3

# Use SwiftUI frontend (macOS 15.0+)
-DFRONTEND=SwiftUI

Build System Requirements

• C++ Standard: C++20 (enforced by CMake)
• Minimum CMake Version: 3.15
• Apple Platforms: Enables Objective-C, Objective-C++, and Swift automatically

Troubleshooting

CMake Configuration Fails

Problem: CMake can’t find dependencies

Solution: Ensure all dependencies are installed via Homebrew:

brew install cmake ninja sdl3 fmt

Submodule Errors

Problem: Missing submodule errors during build

Solution: Reinitialize submodules:

git submodule update --init --recursive

Compilation Errors

Problem: Compiler warnings treated as errors

Solution: Hydra uses -Werror (warnings as errors). Ensure you’re using a compatible Xcode/Clang version:

xcode-select --install

Metal/Graphics Errors

Problem: Metal framework linking errors

Solution: Hydra requires macOS with Metal support. Ensure you’re running on compatible hardware and macOS version.

Hypervisor Framework Errors (Apple Silicon)

Problem: Hypervisor.framework linking fails

Solution: Hypervisor support requires specific entitlements. Try disabling it:

cmake . -B build -G Ninja -DHYPERVISOR_ENABLED=OFF -DMACOS_BUNDLE=ON

SwiftUI Build Issues

Problem: SwiftUI frontend won’t build

Solution: Ensure you’re running macOS 15.0 or later:

sw_vers

If on an older version, use the SDL3 frontend instead:

cmake . -B build -G Ninja -DFRONTEND=SDL3 -DMACOS_BUNDLE=ON

Clean Build

To perform a clean build, remove the build directory:

rm -rf build
cmake . -B build -G Ninja -DMACOS_BUNDLE=ON
ninja -C build

Build Output

After a successful build, you’ll find:

• Executable: build/bin/Hydra.app (when MACOS_BUNDLE=ON)
• Compile Commands: build/compile_commands.json (for IDE integration)

Next Steps

After building Hydra:

1. Configure: Launch Hydra once to generate the config file at ~/Library/Application Support/Hydra/config.toml
2. Setup Firmware: Some games require decrypted firmware files
3. Install Patches: Download the patch set for official games
4. Start Emulating: Load NRO, NCA, or NX format games

For more information on contributing to Hydra, see Contributing.