Building TruchiEmu from Source

Building TruchiEmu from source allows you to access the latest features, contribute to development, or customize the emulator for your needs.

Prerequisites

  • macOS 14.0 (Sonoma) or later
  • Xcode 15+ with Swift 5.9+ support
  • XcodeGen — install via Homebrew: brew install xcodegen
  • Xcode Command Line Tools — install via: xcode-select --install
  • CMake — install via: brew install cmake

Build Steps

  1. Clone the repository 
    git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu
  2. Generate the Xcode project

    Edit project.yml if needed, then run:

    xcodegen generate

    This creates TruchiEmu.xcodeproj from the project specification.

  3. Open in Xcode 
    open TruchiEmu.xcodeproj
  4. Build the project

    In Xcode: Product > Build (Cmd+B), or from the terminal:

    xcodebuild -project TruchiEmu.xcodeproj -scheme TruchiEmu -configuration Debug build

Dependencies

TruchiEmu relies on the following dependencies:

  • Libretro cores: Emulation backends downloaded and managed at runtime
  • SwiftData: Apple's persistent data framework (bundled with Swift)
  • Metal: Apple's GPU framework for shader rendering (bundled with macOS)

Common Build Issues

XcodeGen Not Found

Install via Homebrew: brew install xcodegen. If already installed, ensure it's in your PATH.

Swift Compiler Errors

Ensure you have Xcode 15+ installed and selected: sudo xcode-select -s /Applications/Xcode.app. Verify Swift version with swift --version.

C++ Standard Errors

This project requires gnu++17 (not the LLVM default). Check that project.yml specifies the correct C++ standard under the target's settings.

Missing Bridging Header

If you see ObjC import errors in Swift files, ensure TruchiEmu-Bridging-Header.h is properly configured in the build settings.