shadps4-emu Cross-Compilation Setup: Building PlayStation 4 Emulator Binaries for Any Platform

To cross-compile shadPS4, set CMAKE_OSX_ARCHITECTURES=x86_64 on Apple Silicon Macs for Intel binaries, use the Docker workflow for reproducible Linux builds, or rely on CI runners for Windows targets.

shadPS4 is a modern C++23 PlayStation 4 emulator that uses CMake 3.24+ to support cross-compilation across different architectures. Whether you need to build x86_64 binaries on an Apple Silicon Mac or create reproducible Linux builds in a container, the shadps4-emu cross-compilation setup provides the necessary toolchain configuration.

Architecture Detection Logic in CMakeLists.txt

The cross-compilation detection lives in the root [CMakeLists.txt](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt). The build system first determines the base architecture using a priority chain:

# Determine base architecture

if (APPLE AND CMAKE_OSX_ARCHITECTURES)
    set(BASE_ARCHITECTURE "${CMAKE_OSX_ARCHITECTURES}")
elseif (CMAKE_SYSTEM_PROCESSOR)
    set(BASE_ARCHITECTURE "${CMAKE_SYSTEM_PROCESSOR}")
else()
    set(BASE_ARCHITECTURE "${CMAKE_HOST_SYSTEM_PROCESSOR}")
endif()

The logic then normalizes architecture strings to x86_64 or arm64:

# Normalise architecture strings

if (BASE_ARCHITECTURE MATCHES "(x86)|(X86)|(amd64)|(AMD64)")
    set(ARCHITECTURE "x86_64")
elseif (BASE_ARCHITECTURE MATCHES "(aarch64)|(AARCH64)|(arm64)|(ARM64)")
    set(ARCHITECTURE "arm64")
else()
    message(FATAL_ERROR "Unsupported CPU architecture: ${BASE_ARCHITECTURE}")
endif()

For x86_64 targets, the build forces the x86-64-v3 microarchitecture level:

if (ARCHITECTURE STREQUAL "x86_64")
    add_compile_options(-march=x86-64-v3)
endif()

macOS Cross-Compilation: Apple Silicon to x86_64

The most common cross-compilation scenario for shadPS4 occurs on macOS when building an x86_64 binary on an arm64 (Apple Silicon) host. This is necessary for distributing universal binaries or targeting older Intel Macs.

CMake Configuration for macOS Cross-Compilation

When the host is arm64 and the target is x86_64, the CMakeLists.txt automatically applies special handling:

if (APPLE AND ARCHITECTURE STREQUAL "x86_64" AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "arm64")
    # Exclude Homebrew's ARM-only paths to avoid linking the wrong libraries

    list(APPEND CMAKE_IGNORE_PREFIX_PATH "/opt/homebrew")
    # Reconfigure pkg-config to point at the x86_64 sysroot

    set(ENV{PKG_CONFIG_DIR} "")
    set(ENV{PKG_CONFIG_LIBDIR}
        "${CMAKE_SYSROOT}/usr/lib/pkgconfig:${CMAKE_SYSROOT}/usr/share/pkgconfig:${CMAKE_SYSROOT}/usr/local/lib/pkgconfig:${CMAKE_SYSROOT}/usr/local/share/pkgconfig")
    set(ENV{PKG_CONFIG_SYSROOT_DIR} ${CMAKE_SYSROOT})
endif()

This logic performs three critical functions:

1. Ignores /opt/homebrew – Prevents the ARM64 Homebrew libraries from contaminating the x86_64 link step.
2. Rewrites PKG_CONFIG paths – Forces pkg-config to search the x86_64 sysroot for SDL3, Vulkan, and other dependencies.
3. Sets CMAKE_SYSROOT – Ensures the compiler uses the correct macOS SDK for the target architecture.

Using CMake Presets for macOS

The repository provides a dedicated preset in [CMakeDarwinPresets.json](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeDarwinPresets.json):

{
  "configurePresets": [
    {
      "name": "macos-x86_64",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_OSX_ARCHITECTURES": "x86_64"
      }
    }
  ]
}

To build using the preset:

cmake --preset macos-x86_64
cmake --build --preset macos-x86_64

Alternatively, manual configuration:

cmake -S . -B build/ \
  -DCMAKE_OSX_ARCHITECTURES=x86_64 \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_BUILD_TYPE=Release
cmake --build ./build --parallel$(sysctl -n hw.ncpu)

The resulting shadps4 executable runs under Rosetta 2 on Apple Silicon machines and natively on Intel Macs.

Linux Cross-Compilation with Docker

For reproducible Linux builds across different host distributions, shadPS4 provides a Docker-based workflow defined in documents/Docker Builder/docker-compose.yml.

This approach effectively cross-compiles for a standardized Linux environment regardless of your host OS (Ubuntu, Fedora, Arch, etc.).

Docker Environment Features

The container bundles:

• Clang 19 (latest stable)
• CMake 3.24+
• SDL3 development libraries
• Vulkan SDK
• All third-party dependencies required by the emulator

Building with Docker

Start the container:

cd documents/Docker\ Builder/
docker compose up -d

Enter the build environment:

docker compose exec builder bash

Inside the container, clone and build:

git clone --recursive https://github.com/shadps4-emu/shadPS4.git
cd shadPS4
cmake -S . -B build/ -DCMAKE_BUILD_TYPE=Release
cmake --build ./build --parallel$(nproc)

Extract the binary:

docker cp shadps4-builder:/shadPS4/build/shadps4 ./shadps4

This workflow ensures your Linux binary is built against a consistent toolchain, avoiding host-specific library mismatches.

Windows Build Considerations

Windows builds currently require Visual Studio 2022 or Clang 19 running natively on Windows. Direct cross-compilation from Linux to Windows is not officially supported in the shadps4-emu cross-compilation setup.

For automated Windows builds, the project relies on CI pipelines using Windows runners. If you must build Windows binaries from a Linux host, you can use a Docker image containing the Visual Studio Build Tools, though this is not documented in the main repository and requires manual toolchain configuration.

Summary

• shadPS4 uses CMake 3.24+ with automatic architecture detection in CMakeLists.txt, normalizing host processors to x86_64 or arm64.
• macOS cross-compilation from Apple Silicon to Intel requires setting CMAKE_OSX_ARCHITECTURES=x86_64, ignoring /opt/homebrew, and reconfiguring PKG_CONFIG paths to the x86_64 sysroot.
• Linux cross-compilation is best achieved via the Docker workflow in documents/Docker Builder/docker-compose.yml, which bundles Clang 19 and all dependencies for reproducible builds.
• Windows builds are native-only; use Visual Studio 2022 or Clang 19 on Windows, or CI runners for automated builds.

Frequently Asked Questions

How do I fix Homebrew library errors when cross-compiling for macOS x86_64 on Apple Silicon?

When building for x86_64 on an arm64 Mac, the linker may incorrectly pick up ARM64 libraries from /opt/homebrew. The CMakeLists.txt automatically adds /opt/homebrew to CMAKE_IGNORE_PREFIX_PATH when it detects this cross-compilation scenario. Additionally, it rewrites the PKG_CONFIG environment variables to point to the x86_64 sysroot, ensuring SDL3 and Vulkan libraries are linked correctly.

Can I build shadPS4 for ARM64 Linux?

While the CMake logic supports arm64 as a valid architecture (detected via CMAKE_SYSTEM_PROCESSOR matching aarch64 or arm64), the repository does not provide an official ARM64 Linux toolchain file. You can cross-compile by providing your own CMAKE_TOOLCHAIN_FILE that sets CMAKE_SYSTEM_NAME, CMAKE_SYSTEM_PROCESSOR, and the appropriate cross-compiler paths (e.g., aarch64-linux-gnu-gcc).

Is Docker required for Linux cross-compilation?

Docker is not strictly required if you are building natively on the target architecture. However, if your host Linux distribution differs from the target environment (e.g., building on Fedora for a Debian target), the Docker workflow in documents/Docker Builder/docker-compose.yml is the recommended approach. It ensures a consistent Clang 19 toolchain and eliminates host-specific library mismatches that often break cross-distro builds.

Why can't I cross-compile Windows binaries from Linux?

The shadPS4 build system does not include toolchain definitions for MinGW or MSVC cross-compilation from Linux. Windows builds require the Windows SDK and Visual Studio 2022 (or Clang 19 with MSVC compatibility), which are difficult to replicate in a Linux cross-compilation environment. For automated Windows builds, use the project's CI pipelines which run on Windows runners, or manually configure a Docker image with Visual Studio Build Tools if you absolutely must build from Linux.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}