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

> Learn the shadps4-emu cross-compilation setup to build PlayStation 4 emulator binaries for any platform. Follow our guide for Apple Silicon, Linux Docker, and Windows CI builds for seamless cross-platform emulation.

- Repository: [shadps4-emu/shadPS4](https://github.com/shadps4-emu/shadPS4)
- Tags: how-to-guide
- Published: 2026-03-19

---

**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)](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt)**. The build system first determines the base architecture using a priority chain:

```cmake

# 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`:

```cmake

# 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:

```cmake
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`](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt) automatically applies special handling:

```cmake
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)](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeDarwinPresets.json)**:

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

```

To build using the preset:

```bash
cmake --preset macos-x86_64
cmake --build --preset macos-x86_64

```

Alternatively, manual configuration:

```bash
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`](https://github.com/shadps4-emu/shadPS4/blob/main/documents/Docker%20Builder/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:

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

```

Enter the build environment:

```bash
docker compose exec builder bash

```

Inside the container, clone and build:

```bash
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:

```bash
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`](https://github.com/shadps4-emu/shadPS4/blob/main/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`](https://github.com/shadps4-emu/shadPS4/blob/main/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.