Building for macOS

Minimum macOS

macOS High Sierra (10.13) or higher is required to build Dolphin.

Install Xcode

Xcode is required to build Dolphin. It can be installed from the Mac App Store or from Apple's Developer portal.

After Xcode has been downloaded and installed, the active developer directory must be set with the following command:

sudo xcode-select -s /path/to/Xcode.app/Contents/Developer

Note: Make sure you have the correct version of Xcode installed with the macOS SDK for your OS version. For example, macOS 10.13 runs up to Xcode 10, and Xcode 10 only has the macOS 14 SDK. You can download other versions of Xcode and extract the macOS SDK to add to your existing Xcode installation if needed.

Install Qt

Install Qt5 from the qt.io website

The offline installer can be found here. https://www.qt.io/offline-installers

When it comes to selecting components to install, select the Qt prebuilt components for MacOS.

Export your Qt5_DIR to the folder in your Qt installation with Qt5Config.cmake in it ( this is usually /<your_Qt_installation_folder>/<Qt_version>/clang_64/lib/cmake/Qt5 ) by entering in Terminal: export Qt5_DIR=<path_to_Qt5Config>

Append the Qt5_DIR to your PATH with export PATH=$PATH:$Qt5_DIR

If you plan to rebuild Dolphin in the future you'll probably want to update Qt5_DIR and PATH in your .bash_profile as well.

• Using double quotes: echo "export Qt5_DIR=$Qt5_DIR" >> ~/.bash_profile
• Using single quotes: echo 'export PATH=$PATH:$Qt5_DIR' >> ~/.bash_profile

Checkout and Compile Dolphin

To checkout Dolphin's source:

git clone https://github.com/dolphin-emu/dolphin ~/dolphin-emu
cd ~/dolphin-emu

Pull the git submodules (required for mGBA integration)

git submodule update --init

Download and install CMake if you don't have it.

To build with CMake (optionally verbose):

mkdir -p build
cd build
cmake ..
make

CMake Notes

The -j option can be passed to make in order to compile multiple objects at once. A good rule of thumb is number of CPU cores plus one. For example, on a quad core CPU make -j5 would be a good choice. To use all threads available, run make -j$(nproc).

You can execute cmake -L to view the options that Dolphin's CMake environment supports, as well as their current and possible settings.

If you have any problems compiling, use the verbose option (make VERBOSE=1) to give more detail. If you report a problem, at a minimum include the last screen-full of lines.

To have CMake specify a macOS SDK, add the following flags when calling CMake. Replace 10.XX with the macOS version number. The default location for Xcode to store the macOS SDK is: /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/

-DCMAKE_OSX_SYSROOT=<path_to_SDK>/MacOSX10.XX.sdk/ -DCMAKE_OSX_DEPLOYMENT_TARGET=10.XX

Optional: Ninja

Ninja is a replacement for Make which is a bit faster for a Dolphin-sized project and is worth considering if you intend to rebuild frequently.

After installing it, pass -G Ninja to CMake and use 'ninja' instead of 'make' (note that ninja is -j by default).

By default, Clang won't show color diagnostics when not invoked from a TTY, and Ninja buffers compiler output through a pipe to avoid interleaving issues. To fix this, pass to CMake:

-DCMAKE_CXX_FLAGS="-Xclang -fcolor-diagnostics"

Running Dolphin

After Dolphin is compiled, the .app bundle will be located at dolphin-emu/build/Binaries/Dolphin.app. This can be copied to Applications if desired.

Or to run directly from the build folder:

open ./dolphin-emu/build/Binaries/Dolphin.app

Keeping Up to Date

All you need to do to update to the latest Dolphin revision is the following:

cd ./dolphin-emu
git pull origin
cd build
cmake .. && make

FAQ

When building Dolphin, I get errors

If you are receiving this error:

CMake Error at Source/Core/DolphinQt/CMakeLists.txt:9 (find_package):
  By not providing "FindQt5.cmake" in CMAKE_MODULE_PATH this project has
  asked CMake to find a package configuration file provided by "Qt5", but
  CMake did not find one.

  Could not find a package configuration file provided by "Qt5" (requested
  version 5.9) with any of the following names:

    Qt5Config.cmake
    qt5-config.cmake

  Add the installation prefix of "Qt5" to CMAKE_PREFIX_PATH or set "Qt5_DIR"
  to a directory containing one of the above files.  If "Qt5" provides a
  separate development package or SDK, be sure it has been installed.

Solution 1

If you have Homebrew installed, and you installed QT5 from there, uninstall Homebrew QT5 using this command:

brew uninstall qt5

Then, download the offline installer from qt.io/offline-installers, run the installer inside the DMG file and log in or sign up to/for a QT Account.

On the Installation Folder step, select your home folder.

Then, on the Select Components page, expand the Qt x.x.x section and check the box next to macOS.

After that, click Next, agree to the license(s), click Next again then finally, after all that time...

Click Install.

After it has finished installing, follow these steps:

Export your Qt5_DIR to the folder in your Qt installation with Qt5Config.cmake in it. In this case, it should be:

export Qt5_DIR=~/Qtx.x.x

(Replacing the x's with the version numbers)

Append the Qt5_DIR to your PATH with export PATH=$PATH:$Qt5_DIR

And then... echo "export Qt5_DIR=$Qt5_DIR" >> ~/.bash_profile echo 'export PATH=$PATH:$Qt5_DIR' >> ~/.bash_profile

Now, we can build with CMake (make sure to cd into the Dolphin source folder!):

mkdir -p build
cd build
cmake ..
make