Skip to content

Build instructions

Jump to bottom
WhyNut edited this page Aug 30, 2022 · 136 revisions
Table of Contents
Download the source code
Prerequisites
Building for Windows
Building for Android
Building for Qt platforms
Building for macOS
Building with CMake (Other platforms, e.g. Linux)
Building for iOS
Building for Raspberry Pi OS 64 Bit
Building for Raspbian
Building with Clang 3.4 (Linux)
Packaging

Download the source code

(for additional information that's partially outdated, see the development page)

Install git and check out the source code (git clone --recurse-submodules https://github.com/hrydgard/ppsspp.git, or fork and clone that).

After doing an update, or if you forgot --recurse-submodules, run this command:

git submodule update --init --recursive

in order to update the translations (lang), FFmpeg libraries, and other submodules.

Recommended way to get up-to-date is (git pull --rebase https://github.com/hrydgard/ppsspp.git) and then the above command.

If you choose to build from tarballs of the source code instead of cloning the full git repository, you will need to manually download the tarball releases of each of the submodules as well (submodules are listed in this repo's .gitmodules file).

Prerequisites

First, install Python 3.

Supported Platforms

  • Windows :: Microsoft Visual Studio 2015 Community Edition or higher. NOTE: It is necessary to install the Visual Studio component "Windows XP support for C++", can be found under "Individual Components" to the right in the Visual Studio installer.
  • Linux :: clang/gcc/g++.
    • Debian/Ubuntu sudo apt install build-essential cmake libgl1-mesa-dev libsdl2-dev libvulkan-dev
    • Fedora/RHEL sudo dnf group install "Development Tools"
  • Mac OS X :: Command Line Tools (xcode-select --install). You will also need Homebrew installed with the sdl2, cmake, libzip and snappy packages (brew install sdl2 cmake libzip qt5 snappy).
  • Android :: You should have the latest Android Studio installed. From the SDK manager within, install CMake and NDK.
  • Raspbian :: It seems to be required to compile SDL2 manually, the package doesn't work. See the CMake instructions and Raspberry Pi specific instructions.
  • iOS :: OS X 10.10+ with Xcode 6+ installed. If compiling a fakesigned binary intended for jailbroken iOS, you also need iOSOpenDev installed with a patched iPhoneOS SDK (sudo iod-setup sdk)

Compilers --- you will need one of the following (if you follow the above, you probably have them):

  • Clang :: Minimum version of 3.4 is required. Clang is preferred over GCC.
  • GCC :: Minimum version of 4.8 is required.
  • MSVC :: Minimum version of MSVC 2015 is required, 2017 updated to latest is recommended.

CMake (minimum version of 3.6) is also required if not building on Windows (and you have it if you follow the above Android instructions).

Building for Windows

Open the solution and just build, it'll work. You may just need to set up a path or two to the Windows SDK (which includes the DX SDK) nowadays. A step-by-step compiling guide can be found here.

Building for Android with Android Studio

Open the PPSSPP folder as a project in Android Studio. Change the build variant to "normalOptimized" and build and run. Everything should work, provided you have installed the NDK and CMake properly through the SDK manager.

Building for Qt platforms

The Qt frontend currently supports Linux and any other platform that has Qt available (though not officially, apart from Linux). We use CMake to build for Qt.

A Qt-based frontend is available in the Qt/ dir.

For building the package via command-line, you will need to ensure Qt5 is installed for your target platform (on Linux: Development libraries are qt5-qmake qtsystems5-dev qtmultimedia5-dev qttools5-dev-tools libqt5opengl5-dev for Qt5. Install SDL 1.2 if you want to use USB Gamepad or improve Linux audio. For Qt's built-in audio, use qtmultimedia5-dev on Qt5.). After installing these package components, simply open up the terminal and:

./b.sh --qt

Building for macOS

You need to have the Command Line Tools installed (XCode is not needed):

xcode-select --install

Use Homebrew to install the required dependencies:

brew upgrade
brew install sdl2 cmake libzip qt5 snappy

Then build using:

./b.sh --qtbrew

Or, for Macs with Apple Silicon:

CMAKE_ARGS="-DCMAKE_OSX_ARCHITECTURES=arm64; -DUSE_SYSTEM_LIBPNG=OFF" ./b.sh

Or just

./b.sh

for the SDL build. The latter you can then run like this:

build/PPSSPPSDL.app/Contents/MacOS/PPSSPPSDL

Building with CMake (Other platforms, e.g. Linux)

For Ubuntu (and possibly other distros) make sure to run sudo apt install libgl1-mesa-dev libsdl2-dev.

PPSSPP currently uses CMake on platforms that do not have Qt installed and wish to target SDL or native (iOS/Android/Blackberry) frontends. In order to build for most systems, create a build directory and run:

cmake path/to/ppsspp
make -j 4

or:

./b.sh

You can specify the -G parameter to cmake to choose a generator. The NMake Makefiles, Visual Studio 11 (projects + sln), GNU Makefiles and Unix Makefiles generators have been tested.

Alternatively, run b.sh, on Linux, which will create the directory for you. If you are on Windows, you will need GNU and CMake to run the bash scripts.
When using Intel integrated Graphics and Ubuntu 20.04 or newer you have to launch PPSSPPSDL with the following command to load the old drivers and prevent a crash:

MESA_LOADER_DRIVER_OVERRIDE=i965 ./build/PPSSPPSDL

Building for iOS (Serena's method):

(Most up to date as of 2022)

  1. Make sure you have Xcode installed and that Xcode is in your /Applications folder
  2. Run cmake -DCMAKE_TOOLCHAIN_FILE=./cmake/Toolchains/ios.cmake -DIOS_PLATFORM=OS -DCMAKE_IOS_SDK_ROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk -H. -Bbuild.ios -GXcode
  3. Open the Xcodeproj in ./build.ios/PPSSPP.xcodeproj
  4. In Xcode, press on the xcodeproj, then highlight all the targets, change the archetiture from arm64 and arm7 to just arm64, and set the deployment target from iOS 6 to something higher (as Xcode doesn't support iOS 6 anymore), as seen in the video
  5. Choose PPSSPP in the top bar and press Build or Run
  6. PPSPP will now compile!

Building for iOS (mariolopjr's method)

From https://github.com/hrydgard/ppsspp/issues/11905:

  1. Follow PPSSPP cloning instructions
  2. Download Xcode 9.4.1 from https://developer.apple.com/download/more/, extract from .xip file, rename to Xcode-9.4.1, and copy to Applications
  3. Run the following command (instead of the one from the wiki): cmake -DCMAKE_TOOLCHAIN_FILE=./cmake/Toolchains/ios.cmake -DIOS_PLATFORM=OS -DCMAKE_IOS_SDK_ROOT=/Applications/Xcode-9.4.1.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS11.4.sdk -H. -Bbuild.ios -GXcode
  4. Navigate to build.ios, open PPSSPP.xcodeproj in Xcode-9.4.1, set the signing stuff, and then build the app
  5. Install the .app as necessary, or navigate to the built .app, create Payload folder and move .app into it, and create an ipa using the following command zip -r9 PPSSPP.ipa Payload/PPSSPP.app, and use Cydia Impactor to install.

You should have an updated PPSSPP version, built on iOS 11 SDK (that should help with crashes)!

Building for iOS (CMake)

Run the script:

./b.sh --ios

Then open the generated project in Xcode using: open *.xcodeproj Or use the command line: xcodebuild -configuration Release

Alternate method which seems to work better:

cmake -DCMAKE_TOOLCHAIN_FILE=./cmake/Toolchains/ios.cmake -DIOS_PLATFORM=OS -H. -Bbuild.ios -GXcode
cd build.ios
open PPSSPP.xcodeproj

For running in simulator: cmake -DCMAKE_TOOLCHAIN_FILE=./cmake/Toolchains/ios.cmake -DIOS_PLATFORM=SIMULATOR -H. -Bbuild.ios -GXcode

Then go to the target, and set developer profile as iOS developer. Go to the General tab of the target and check the box to automatically manage signing. After that, things should work.

The PPSSPP.app bundle will be in /path/to/ppsspp/build-ios/Release-iphoneos/PPSSPP.app. You may then scp or afc it to /Applications/ and launch PPSSPP.

If this is your first time installing PPSSPP to your iOS device, you may need to run uicache as mobile in a terminal session to rebuild the SpringBoard UICache, or simply reboot.

See https://github.com/hrydgard/ppsspp/issues/5441 and https://github.com/hrydgard/ppsspp/issues/7880 for some troubleshooting information.

Building for Raspberry Pi OS 64 Bit

  1. Install prerequisites: sudo apt install clang cmake libgl1-mesa-dev libsdl2-dev libvulkan-dev

  2. Change the compiler from GCC to Clang sudo update-alternatives --config cc and sudo update-alternatives --config c++

  3. Compile using ./b.sh --rpi64

Building for Raspbian

GCC is preinstalled, but you can use sudo update-alternatives --config cc and sudo update-alternatives --config c++ to switch to Clang.

Make sure to include -DCMAKE_TOOLCHAIN_FILE=cmake/Toolchains/raspberry.armv7.cmake when using cmake. For armv6 devices, you'll need to use -DCMAKE_TOOLCHAIN_FILE=cmake/Toolchains/raspberry.armv6.cmake. See also ./b.sh --rpi.

Note that echo 5 | sudo tee /sys/devices/system/cpu/cpufreq/ondemand/up_threshold will improve performance but increase temperatures. You may always want the legacy GL driver and to update firmware, as well as allocate more RAM to the GPU.

If you're using a windowing environment, remember to exit it (i.e. Ctrl-Alt-F1, Ctrl-Alt-F7 to get back) when starting PPSSPPSDL.

See https://github.com/hrydgard/ppsspp/issues/7479 for more information.

Building with Clang 3.4 (Linux)

In order to build it under Clang environment, you will need clang-3.4 packages from the repository and install it. Then, you will need to run the command to locate where is bits/c++config.h:

locate bits/c++config.h

Usually, the c++config.h located at /usr/include/<arch>/c++/<version>/bits depending kinds of machine and installation. After located the c++config.h and other header file components, simply copy the c++config.h and other header files to /usr/include/c++/<version>/bits and placed it into the location in order to make Clang building the project without problems.

Clang works perfectly with Cmake build method, so you might need to do something before building it is run the command to set the Clang as the working compiler before building it via Cmake method:

export CC=clang
export CXX=clang++

You can also put these command into .bashrc file to make it as a default compiler.

Packaging

For all platforms, the application is automatically packaged in to an installable file (.app for iOS and macOS, .exe for Windows and a standalone binary on Linux).

Clone this wiki locally