Getting Started

Getting Started

This page covers cloning, building, and your first run. For deeper coverage of the contributor workflow see Contributing; for new-game bring-up see Adding a New Game.

Requirements

Tool	Minimum
CMake	3.20
C++ compiler	GCC 11 / Clang 13 (C++20)
SDL2	any recent
OpenGL	3.3
Python	3.8 (for tools/ scripts)

Ubuntu / Debian:

sudo apt install cmake build-essential libsdl2-dev libgl-dev

Fedora / RHEL:

sudo dnf install cmake gcc-c++ SDL2-devel mesa-libGL-devel

macOS (Homebrew):

brew install cmake sdl2

Clone and build

git clone --recurse-submodules https://github.com/PS1Recomp/ps1-recomp.git
cd ps1-recomp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

--recurse-submodules is required — the project uses ELFIO, toml11, fmt and googletest as git submodules.

Build without a game ROM

All tests and the full pipeline build without any game files. Use PS1RECOMP_USE_STUB=ON:

cmake -B build -DCMAKE_BUILD_TYPE=Release \
               -DPS1RECOMP_USE_STUB=ON \
               -DPS1RECOMP_BUILD_TESTS=ON
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

This is the configuration CI runs on every push (557/557 green).

Build with the GUI studio (optional)

cmake -B build -DCMAKE_BUILD_TYPE=Release -DPS1RECOMP_BUILD_INTERFACE=ON
cmake --build build -j$(nproc)
./build/ps1Interface/ps1Interface

The studio opens an ImGui-based explorer for loading ELFs, browsing functions and editing TOML configs before running the full pipeline.

Running a game

Disc images are not included for legal reasons. You need your own legal copy. The disc path is configured per-game and can point to any folder.

1. Place your disc image anywhere and note the path.

2. Generate a config:

   ./build/ps1Analyzer/ps1Analyzer \
       --disc "/path/to/Rayman (USA).cue" \
       --out configs/rayman.toml

3. Recompile MIPS to C++:

   ./build/ps1Recomp/ps1Recomp configs/rayman.toml \
                               ps1Runtime/src/recompiled_out.cpp

4. Rebuild and run:

   cmake --build build -j$(nproc)
   ./build/ps1Runtime/ps1Runtime --config configs/rayman.toml

For Crash Bandicoot 1 the same workflow applies, plus an environment-gated workaround for the boot hang — see the Crash Bandicoot 1 page.

Optional: build with sanitizers

cmake -B build-asan -DPS1RECOMP_ASAN=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build-asan -j$(nproc)

Combines AddressSanitizer + UndefinedBehaviorSanitizer. Used periodically to catch lifetime and signed-overflow bugs.

Run tests

ctest --test-dir build --output-on-failure -j$(nproc)

Single subsystem:

./build/ps1Test/ps1Test --gtest_filter="GpuTest.*"

Where to go next

• New to the architecture? Read Architecture.
• Trying a new title? Read Adding a New Game.
• Something hangs? Read Debugging Tips.