Skip to content

Commit

Permalink
Readme.md: rework build instructions
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@guijan
guijan committed May 3, 2024
1 parent 5817be7 commit 0e63389
Showing 1 changed file with 111 additions and 94 deletions.
205 changes: 111 additions & 94 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down

0 comments on commit 0e63389

Please sign in to comment.