shadps4-emu Common Build Issues and Solutions: A Complete Troubleshooting Guide

Most shadPS4 build failures stem from missing system dependencies, outdated Clang compilers, or uninitialized Git submodules, all of which can be resolved by following the platform-specific documentation and ensuring Clang 18+ is used with the Vulkan SDK on your PATH.

The shadps4-emu/shadPS4 repository is a modern PlayStation 4 emulator written in C++23 that relies on CMake and numerous third-party libraries. Due to its complex dependency chain—including Boost, Vulkan, FFmpeg, and SDL3—developers frequently encounter build-time errors that fall into predictable categories. This guide addresses the most common shadps4-emu build issues with specific fixes derived from the source code and official documentation.

Missing Dependencies and CMake Configuration Errors

Boost, VulkanHeaders, and SDL3 Detection Failures

CMake frequently aborts with Could NOT find <Package> errors when required libraries are not installed or visible. Common missing packages include Boost, VulkanHeaders, SDL3, and FFmpeg.

On Ubuntu and Debian-based systems, install the full dependency set before configuring:

sudo apt install build-essential clang cmake libasound2-dev libpulse-dev libopenal-dev libssl-dev zlib1g-dev libedit-dev libudev-dev libevdev-dev libsdl2-dev libjack-dev libsndio-dev libvulkan-dev vulkan-validationlayers libpng-dev

For the complete Linux dependency list, refer to [documents/building-linux.md](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md).

Git Submodule Initialization Errors

aerolib.cpp and External Library Path Errors

If you see errors such as src/core/aerolib/aerolib.cpp: No such file or directory, the repository's Git submodules have not been initialized. The shadPS4 project includes external libraries as submodules that must be fetched separately.

Clone recursively from the start:

git clone --recursive https://github.com/shadps4-emu/shadPS4

Or, if you already cloned shallowly, initialize the submodules manually:

git submodule update --init --recursive

This instruction is documented in the Cloning section of [README.md](https://github.com/shadps4-emu/shadPS4/blob/main/README.md).

Compiler Version and C++23 Compatibility Issues

Clang 18+ Requirement and Configuration

shadPS4 requires Clang 18+ (or Clang 19 on Windows) because it uses C++23 features not available in older compilers. If CMake warns that "Clang 18 is the recommended compiler" or the build fails with C++23 syntax errors, you must explicitly set the compiler:

cmake -S . -B build \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++

The compiler recommendation appears at the top of [documents/building-linux.md](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-linux.md).

PIE (Position-Independent Executable) Warnings

On some Linux distributions, CMake may print WARNING: PIE is not supported at link time. This occurs when the toolchain lacks Position-Independent Executable support.

Use a recent Clang or GCC that supports PIE, or add the flags manually:

cmake -S . -B build -DCMAKE_POSITION_INDEPENDENT_CODE=ON

The PIE detection logic resides in [CMakeLists.txt lines 22–31](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt#L22).

Platform-Specific Build Failures

Windows: MSYS2 Toolchain Limitations

The shadPS4 project explicitly warns that "Building with MSYS2 is broken" due to missing LLVM/Clang flags in the current MSYS2 toolchain. Do not use MSYS2/MinGW for building.

Instead, use Visual Studio 2022 (Option 1) or VSCode + Build Tools (Option 2) as documented in [documents/building-windows.md lines 5–9](https://github.com/shadps4-emu/shadPS4/blob/main/documents/building-windows.md#option-3-msys2mingw).

Linux: Vulkan SDK and Driver Compatibility

Build failures in src/video_core/renderer_vulkan/* with "Vulkan headers not found" indicate the Vulkan SDK is missing or its bin directory is not on PATH.

Install the SDK from vulkan.lunarg.com and verify installation:

vulkaninfo

Ensure spirv-cross and glslc remain accessible in PATH, as noted in [documents/patching-shader.md](https://github.com/shadps4-emu/shadPS4/blob/main/documents/patching-shader.md).

SDL3 vs SDL2 Mismatch on Input Handling

Errors in src/input/* regarding missing SDL.h typically result from installing the wrong SDL development package. The Windows build defaults to SDL3, while Linux may use SDL2 on older distributions.

Install the correct package for your platform:

• Debian 12+ or Ubuntu 24.04+: libsdl3-dev
• Older distros: libsdl2-dev

CMake selects the target via find_package(SDL3 CONFIG) in [CMakeLists.txt lines 233–236](https://github.com/shadps4-emu/shadPS4/blob/main/CMakeLists.txt#L233).

Optimizing Build Configuration

Disabling Optional Features for Faster Debug Builds

To reduce compile times during development, disable non-essential features such as Discord RPC and the auto-updater:

cmake -S . -B build \
      -DENABLE_DISCORD_RPC=OFF \
      -DENABLE_UPDATER=OFF \
      -DCMAKE_BUILD_TYPE=Debug

Specifying Boost Versions Manually

When multiple Boost versions exist on your system, force CMake to use a specific installation:

cmake -S . -B build \
      -DBOOST_ROOT=/opt/boost_1_84_0 \
      -DCMAKE_PREFIX_PATH=/opt/boost_1_84_0

Summary

• Missing dependencies are the most common cause of CMake failures; install the full package list from documents/building-<os>.md before configuring.
• Uninitialized submodules cause "file not found" errors for src/core/aerolib/aerolib.cpp; always clone with --recursive or run git submodule update --init --recursive.
• Compiler version matters: shadPS4 requires Clang 18+ for C++23 support; set CMAKE_C_COMPILER and CMAKE_CXX_COMPILER explicitly if CMake selects the wrong toolchain.
• Platform-specific pitfalls include broken MSYS2 support on Windows, missing Vulkan SDK paths on Linux, and SDL3/SDL2 mismatches in src/input/*.
• Build optimization flags like -DENABLE_DISCORD_RPC=OFF and manual Boost root specifications can significantly speed up development cycles.

Frequently Asked Questions

Why does CMake fail to find Boost even after I installed it?

CMake relies on find_package(Boost) to locate headers and libraries. If Boost is installed in a non-standard directory or if the version is too old, CMake cannot detect it. Resolve this by installing the development packages (libboost-all-dev on Ubuntu) or explicitly pointing CMake to the installation with -DBOOST_ROOT=/path/to/boost.

Can I build shadPS4 with GCC instead of Clang?

While GCC might compile the project, shadPS4 officially requires Clang 18+ (or Clang 19 on Windows) because it utilizes C++23 features and LLVM-specific optimizations that are not fully supported in older GCC releases. For the most stable build experience, always use the recommended Clang version specified in documents/building-linux.md.

How do I fix "aerolib.cpp: No such file or directory" errors?

This error indicates that Git submodules containing external libraries were not fetched during the clone. Run git submodule update --init --recursive from the repository root to download the missing dependencies. In the future, use git clone --recursive https://github.com/shadps4-emu/shadPS4 to ensure all submodules are present from the start.

What is the minimum Vulkan version required for shadPS4?

shadPS4 requires Vulkan 1.3 with specific format feature flags supported by your GPU driver. If you encounter runtime warnings about "missing format feature flags" or build errors in src/video_core/renderer_vulkan/*, ensure you have installed the latest Vulkan SDK from LunarG and that your GPU drivers are up to date. Verify installation by running vulkaninfo from your terminal.

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