From 0e633892fd4ad5e0764629282441799936c402c7 Mon Sep 17 00:00:00 2001 From: Guilherme Janczak Date: Fri, 3 May 2024 20:24:43 +0000 Subject: [PATCH] Readme.md: rework build instructions This commit's primary goals are to remove duplication in build instructions, and to reduce the total time spent compiling when following the instructions: - Recommend using Ninja with CMake, the compilation time is 11% faster with Ninja on my machine. - Recommend shallow fetches to speed up downloads. - Reduce repetition of build instructions across platforms by documenting a step-by-step compilation approach with shared steps between OSes. - Recommend shorter, standard CMake flags (`-B` and `--build`) instead of calling the generated build system directly and working around its limitations. - Syntax highlight Shell examples. - Let Ninja figure out the job count. A cursory look at its source code indicates it takes more than just core count into account, it also understands CGroups and processor affinities. - Fix lack of commas where necessary in the lines we've modified. - Break up lines over 80 characters in the parts of the text we've modified. This doesn't affect presentation in Markdown. - Title the Windows uninstall instructions "Microsoft Windows uninstall" to avoid having multiple sections named "Microsoft Windows," as it would prevent linking all but the first. --- Readme.md | 205 +++++++++++++++++++++++++++++------------------------- 1 file changed, 111 insertions(+), 94 deletions(-) diff --git a/Readme.md b/Readme.md index 3c9dc84730c3..ebdc4cf3abf3 100644 --- a/Readme.md +++ b/Readme.md @@ -16,7 +16,7 @@ Please read the [FAQ](https://dolphin-emu.org/docs/faq/) before using Dolphin. * Windows (10 or higher). * Linux. * macOS (10.15 Catalina or higher). - * Unix-like systems other than Linux are not officially supported but might work. + * Unix-like systems other than Linux are not officially supported, but might work. * Processor * A CPU with SSE2 support. * A modern CPU (3 GHz and Dual Core, not older than 2008) is highly recommended. @@ -36,118 +36,135 @@ Please read the [FAQ](https://dolphin-emu.org/docs/faq/) before using Dolphin. Dolphin can only be installed on devices that satisfy the above requirements. Attempting to install on an unsupported device will fail and display an error message. -## Building for Windows +## Building +Compilation is split into several steps, with minor differences between +operating systems. +### Fetch +Download Dolphin's source code, enter the newly downloaded source tree, and +download the embedded dependencies as git submodules: +```sh +git clone --depth 1 https://github.com/dolphin-emu/dolphin && + cd dolphin && + git submodule update --depth 1 --init --recursive +``` +In the example, only the latest commit is downloaded to speed up the process. If +the complete git history is needed, remove `--depth 1` from the commands. To +download the complete history after a shallow download, run the following +command from the project's directory: +```sh +git fetch --unshallow +``` + +### Compile +#### Microsoft Windows Use the solution file `Source/dolphin-emu.sln` to build Dolphin on Windows. Dolphin targets the latest MSVC shipped with Visual Studio or Build Tools. Other compilers might be able to build Dolphin on Windows but have not been -tested and are not recommended to be used. Git and latest Windows SDK must be -installed when building. - -Make sure to pull submodules before building: +tested and are not recommended to be used. Git and the latest Windows SDK must +be installed when building. + +The "Release" solution configuration includes performance optimizations for the +best user experience, but complicates debugging Dolphin. The "Debug" solution +configuration is significantly slower, more verbose and less permissive, but +makes debugging Dolphin easier. + +#### Linux, macOS, FreeBSD, and other Unix or Unix-like operating systems. +Dolphin requires [CMake](https://cmake.org/) for systems other than Windows. +You need a recent version of GCC or Clang with decent C++20 support. CMake will +inform you if your compiler is too old. Many libraries are bundled with Dolphin +and used if they're not installed on your system. CMake will inform you if a +bundled library is used or if you need to install any missing packages yourself. +You may refer to the +[wiki](https://github.com/dolphin-emu/dolphin/wiki/Building-for-Linux) for more +information. + +Additionally, [Ninja](https://ninja-build.org/) is recommended for faster +compilation times. + +From inside the checked-out source tree, run: ```sh -git submodule update --init --recursive +cmake -G Ninja -B build && + cmake --build build ``` -The "Release" solution configuration includes performance optimizations for the best user experience but complicates debugging Dolphin. -The "Debug" solution configuration is significantly slower, more verbose and less permissive but makes debugging Dolphin easier. +Binaries will be available in `build/Binaries`. On macOS, an application bundle +will be created in the same directory. + +#### Android +These instructions assume familiarity with Android development. If you do not +have an Android dev environment set up, see [AndroidSetup.md](AndroidSetup.md). -## Building for Linux and macOS +If using Android Studio, import the Gradle project located at +`./Source/Android`. -Dolphin requires [CMake](https://cmake.org/) for systems other than Windows. -You need a recent version of GCC or Clang with decent c++20 support. CMake will -inform you if your compiler is too old. -Many libraries are bundled with Dolphin and used if they're not installed on -your system. CMake will inform you if a bundled library is used or if you need -to install any missing packages yourself. You may refer to the [wiki](https://github.com/dolphin-emu/dolphin/wiki/Building-for-Linux) for more information. +Android apps are compiled using a build system called Gradle. Dolphin's native +component, however, is compiled using CMake. The Gradle script will attempt to +run a CMake build automatically while building the Java code. -Make sure to pull submodules before building: +### Extra steps +#### Installation via CMake +To install Dolphin to your system: ```sh -git submodule update --init --recursive +cmake --install build ``` -### macOS Build Steps: - -A binary supporting a single architecture can be built using the following steps: - -1. `mkdir build` -2. `cd build` -3. `cmake ..` -4. `make -j $(sysctl -n hw.logicalcpu)` - -An application bundle will be created in `./Binaries`. - -A script is also provided to build universal binaries supporting both x64 and ARM in the same -application bundle using the following steps: - -1. `mkdir build` -2. `cd build` -3. `python ../BuildMacOSUniversalBinary.py` -4. Universal binaries will be available in the `universal` folder - -Doing this is more complex as it requires installation of library dependencies for both x64 and ARM (or universal library -equivalents) and may require specifying additional arguments to point to relevant library locations. -Execute BuildMacOSUniversalBinary.py --help for more details. - -### Linux Global Build Steps: - -To install to your system. - -1. `mkdir build` -2. `cd build` -3. `cmake ..` -4. `make -j $(nproc)` -5. `sudo make install` - -### Linux Local Build Steps: - -Useful for development as root access is not required. - -1. `mkdir Build` -2. `cd Build` -3. `cmake .. -DLINUX_LOCAL_DEV=true` -4. `make -j $(nproc)` -5. `ln -s ../../Data/Sys Binaries/` - -### Linux Portable Build Steps: - -Can be stored on external storage and used on different Linux systems. -Or useful for having multiple distinct Dolphin setups for testing/development/TAS. - -1. `mkdir Build` -2. `cd Build` -3. `cmake .. -DLINUX_LOCAL_DEV=true` -4. `make -j $(nproc)` -5. `cp -r ../Data/Sys/ Binaries/` -6. `touch Binaries/portable.txt` - -## Building for Android - -These instructions assume familiarity with Android development. If you do not have an -Android dev environment set up, see [AndroidSetup.md](AndroidSetup.md). - -Make sure to pull submodules before building: +#### CMake local build +Pass `-DLINUX_LOCAL_DEV=true` to CMake when creating the build directory, and +put a symlink to Dolphin's assets in the same directory as the binaries: ```sh -git submodule update --init --recursive +cmake -DLINUX_LOCAL_DEV=true -G Ninja -B build && + cmake --build build && + ln -s Data/Sys build/Binaries/ ``` +Useful for development, as root access is not required. -If using Android Studio, import the Gradle project located in `./Source/Android`. - -Android apps are compiled using a build system called Gradle. Dolphin's native component, -however, is compiled using CMake. The Gradle script will attempt to run a CMake build -automatically while building the Java code. - -## Uninstalling - -On Windows, simply remove the extracted directory, unless it was installed with the NSIS installer, -in which case you can uninstall Dolphin like any other Windows application. +#### CMake portable build +Pass `-DLINUX_LOCAL_DEV=true` to CMake when creating the build directory, +copypaste Dolphin's assets into the same directory as the binaries, and create a +`portable.txt` file in the same directory as the binaries: +```sh +cmake -DLINUX_LOCAL_DEV=true -G Ninja -B build && + cmake --build build && + cp -r Data/Sys build/Binaries/ && + touch build/Binaries/portable.txt +``` +`build/Binaries` can be stored on external storage and used on different +systems. Also useful for having multiple distinct Dolphin setups for testing, +development, or TAS. + +#### macOS universal binaries +Doing this is more complex as it requires installation of library dependencies +for both x64 and ARM (or universal library equivalents) and may require +specifying additional arguments to point to relevant library locations. +Run the following command for more details: +```sh +BuildMacOSUniversalBinary.py --help +``` +To build universal binaries supporting both x64 and ARM in the same application +bundle, run the following command: +```sh +mkdir build && + (cd build && python ../BuildMacOSUniversalBinary.py) +``` +Universal binaries will be available in the `build/universal` folder. -Linux users can run `cat install_manifest.txt | xargs -d '\n' rm` as root from the build directory -to uninstall Dolphin from their system. +### Uninstalling +#### Microsoft Windows uninstall +On Windows, simply remove the extracted directory, unless it was installed with +the NSIS installer, in which case you can uninstall Dolphin like any other +Windows application. -macOS users can simply delete Dolphin.app to uninstall it. +#### macOS +macOS users can delete Dolphin.app to uninstall it. -Additionally, you'll want to remove the global user directory if you don't plan on reinstalling Dolphin. +#### Linux, FreeBSD, and other Unix or Unix-like operating systems +To uninstall Dolphin on other systems, run the following command as root: +```sh +cat install_manifest.txt | tr -d '\n' | xargs rm +``` +Additionally, you'll want to remove the global user directory if you don't plan +on reinstalling Dolphin. ## Command Line Usage