Developer Guide

Contributing to the ultimate macOS retro gaming experience

Development Environment

TruchiEmu is a modern macOS application. To contribute, you will need:

  • macOS: 14.0 (Sonoma) or later
  • Xcode: Latest stable version (supporting Swift 5.9+)
  • XcodeGen: Required for project generation (brew install xcodegen)
  • C++ Standard: gnu++17 / gnu17

The Build Pipeline

We use XcodeGen to manage the project structure. This prevents merge conflicts in the .xcodeproj file and keeps the repository clean.

Standard Build Workflow

# 1. Clone the repository
git clone https://github.com/JuanchoGithub/truchiemu.git
cd truchiemu

# 2. Generate the Xcode project
xcodegen generate

# 3. Build the project
xcodebuild -project TruchiEmu.xcodeproj -scheme TruchiEmu -configuration Debug build

Alternatively, you can run open TruchiEmu.xcodeproj and build using ⌘+B in Xcode.

Adding Source Files

Adding new files to the project requires a specific step because the Xcode project is generated dynamically.

⚠️ Critical: Simply adding a file to a folder in Finder will NOT include it in the Xcode build.

  1. Add your .swift, .mm, or .metal file to the appropriate directory.
  2. Run xcodegen generate in the terminal.
  3. The file will now appear in the Xcode project navigator and be included in the next build.

Project Architecture

TruchiEmu follows a modular architecture to separate the emulation engine from the native macOS UI.

Core Engine

Located in TruchiEmu/Core/Engine/. A mix of Objective-C++ and C that interfaces with libretro via a bridging header.

SwiftUI Layer

Located in TruchiEmu/Views/ and TruchiEmu/Features/. Handles all user interaction and visual presentation.

Services Layer

Located in TruchiEmu/Services/. Manages business logic like save directories, ROM identification, and API integrations.

Testing & QA

We maintain a suite of unit tests to ensure stability across updates.

Running Tests via CLI

xcodebuild test -scheme TruchiEmuTests -destination 'platform=macOS'

Tests are located in the TruchiEmuTests/ directory and cover critical services like ROM identification and DAT prepopulation.

CLI Reference

TruchiEmu provides a command-line interface (CLI) for power users to launch games and manage the application externally.

CLI Launch Example

# Launch the application with a specific ROM path
./TruchiEmu --launch "/path/to/game.nes"

The CLI is handled by CLIManager and CLILauncher, allowing for integration with macOS Shortcuts or third-party launchers.