docs: Improve building.md file (#1530)

* docs: Improve building.md file - Fix broken XCode link - Add MacOS running instructions - Alphabetize linux packages * fix: collapse packages sections for readability * fix: collapse packages sections for readability * fix: add --dvd flag to specify iso path * fix: Remove incorrect info about game.iso
2026-08-09 02:15:44 -04:00 · 2026-05-17 15:51:38 +02:00
parent a499877c37
commit 31dd069879
1 changed files with 183 additions and 53 deletions
@@ -1,50 +1,164 @@
-### Building
-#### Prerequisites
+# Building Dusklight
+
+## Dependencies
+
+The following dependencies are required:
+
 * [CMake 3.25+](https://cmake.org)
-    * Windows: Install `CMake Tools` in Visual Studio
-    * macOS: `brew install cmake`
 * [Python 3+](https://python.org)
-    * Windows: [Microsoft Store](https://go.microsoft.com/fwlink?linkID=2082640)
-        * Verify it's added to `%PATH%` by typing `python` in `cmd`.
-    * macOS: `brew install python@3`
-* **[Windows]** [Visual Studio 2026 Community](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx)
-    * Select `C++ Development` and verify the following packages are included:
-        * `Windows 11 SDK`
-        * `CMake Tools`
-        * `C++ Clang Compiler`
-        * `C++ Clang-cl`
-* **[macOS]** [Xcode 16.4+](https://developer.apple.com/xcode/download/)
-* **[Linux]** Actively tested on Ubuntu 24.04, Arch Linux & derivatives.
-    * Ubuntu 24.04+ packages
-      ```
-      build-essential curl git ninja-build clang lld zlib1g-dev libcurl4-openssl-dev \
-      libglu1-mesa-dev libdbus-1-dev libvulkan-dev libxi-dev libxrandr-dev libasound2-dev libpulse-dev \
-      libudev-dev libpng-dev libncurses5-dev cmake libx11-xcb-dev python3 python-is-python3 \
-      libclang-dev libfreetype-dev libxinerama-dev libxcursor-dev python3-markupsafe libgtk-3-dev \
-      libxss-dev libxtst-dev
-      ```
-     * Arch Linux packages
-       ```
-       base-devel cmake ninja llvm vulkan-headers python python-markupsafe clang lld alsa-lib libpulse libxrandr freetype2
-       ```
-     * Fedora packages
-       ```
-       cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel
-       ```
-         * It's also important that you install the developer tools and libraries
-           ```
-           sudo dnf groupinstall "Development Tools" "Development Libraries"
-           ```
-#### Setup
-Clone and initialize the Dusklight repository
+
+### Windows
+
+* Install [CMake 3.25+](https://cmake.org) by searching `CMake Tools` in Visual Studio
+* Install Python 3 from the [Microsoft Store](https://go.microsoft.com/fwlink?linkID=2082640) and verify it's added to `%PATH%` by typing `python` in `cmd`.
+
+Recommended IDEs:
+
+* [Visual Studio 2026 Community](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx). During installation:
+  * Select `C++ Development` and verify the following packages are included:
+    * `Windows 11 SDK`
+    * `CMake Tools`
+    * `C++ Clang Compiler`
+    * `C++ Clang-cl`
+
+### macOS
+
+* Make sure [Homebrew](https://brew.sh) is installed
+* Install [CMake 3.25+](https://cmake.org)
+
 ```sh
-git clone --recursive https://github.com/TwilitRealm/dusklight.git
-cd dusklight
-git pull
-git submodule update --init --recursive
+brew install cmake
 ```

-#### Building
+* Install Python 3
+
+```sh
+brew install python@3
+```
+
+Recommended IDEs:
+
+* [Xcode 16.4 or later](https://developer.apple.com/xcode/)
+* [Visual Studio Code](https://code.visualstudio.com/download/)
+* [CLion](https://www.jetbrains.com/clion/)
+
+### Linux
+
+Actively tested on Ubuntu 24.04, Arch Linux & derivatives.
+
+**Ubuntu 24.04+ packages**
+
+<details>
+<summary>Click to expand</summary>
+
+* Run the following command to install the required dependencies:
+
+```sh
+sudo apt update && sudo apt install -y \
+    build-essential \
+    clang \
+    cmake \
+    curl \
+    git \
+    libasound2-dev \
+    libclang-dev \
+    libcurl4-openssl-dev \
+    libdbus-1-dev \
+    libfreetype-dev \
+    libglu1-mesa-dev \
+    libgtk-3-dev \
+    libncurses5-dev \
+    libpng-dev \
+    libpulse-dev \
+    libudev-dev \
+    libvulkan-dev \
+    libx11-xcb-dev \
+    libxcursor-dev \
+    libxi-dev \
+    libxinerama-dev \
+    libxrandr-dev \
+    libxss-dev \
+    libxtst-dev \
+    lld \
+    ninja-build \
+    python-is-python3 \
+    python3 \
+    python3-markupsafe \
+    zlib1g-dev
+```
+
+</details>
+<br>
+
+**Arch Linux packages**
+
+<details>
+<summary>Click to expand</summary>
+
+* Run the following command to install the required dependencies:
+
+```sh
+sudo pacman -S --needed \
+    alsa-lib \
+    base-devel \
+    clang \
+    cmake \
+    freetype2 \
+    libpulse \
+    libxrandr \
+    lld \
+    llvm \
+    ninja \
+    python \
+    python-markupsafe \
+    vulkan-headers
+```
+
+</details>
+<br>
+
+**Fedora packages**
+
+<details>
+<summary>Click to expand</summary>
+
+* Run the following command to install the required dependencies:
+
+```sh
+sudo dnf install -y \
+    clang-devel \
+    cmake \
+    libpng-devel \
+    llvm-devel \
+    ninja-build \
+    vulkan-headers
+```
+
+* It's also important that you install the developer tools and libraries
+
+```sh
+sudo dnf groupinstall \
+    "Development Libraries" "Development Tools"
+```
+
+</details>
+<br>
+
+Recommended IDEs:
+
+* [CLion](https://www.jetbrains.com/clion/)
+* [Visual Studio Code](https://code.visualstudio.com/download/)
+
+## Building
+
+* Clone and initialize the Dusklight repository:
+
+```sh
+git clone --recursive https://github.com/TwilitRealm/dusklight.git
+git pull
+cd dusklight
+git submodule update --init --recursive
+```

 **CLion (Windows / macOS / Linux)**

@@ -64,7 +178,8 @@ cmake --build --preset macos-default-relwithdebinfo
 ```

 Alternate presets available:
- `macos-default-debug`: Clang, Debug
+
+* `macos-default-debug`: Clang, Debug

 **ninja (Linux)**

@@ -74,9 +189,10 @@ cmake --build --preset linux-default-relwithdebinfo
 ```

 Alternate presets available:
- `linux-default-debug`: GCC, Debug
- `linux-clang-relwithdebinfo`: Clang, RelWithDebInfo
- `linux-clang-debug`: Clang, Debug
+
+* `linux-default-debug`: GCC, Debug
+* `linux-clang-relwithdebinfo`: Clang, RelWithDebInfo
+* `linux-clang-debug`: Clang, Debug

 **ninja (Windows)**

@@ -86,13 +202,27 @@ cmake --build --preset windows-msvc-relwithdebinfo
 ```

 Alternate presets available:
- `windows-msvc-debug`: MSVC, Debug
- `windows-clang-relwithdebinfo`: Clang-cl, RelWithDebInfo
- `windows-clang-debug`: Clang-cl, Debug

-#### Running
-Pass the disc image as a positional argument. Supported formats: ISO (GCM), RVZ, WIA, WBFS, CISO, GCZ
+* `windows-msvc-debug`: MSVC, Debug
+* `windows-clang-relwithdebinfo`: Clang-cl, RelWithDebInfo
+* `windows-clang-debug`: Clang-cl, Debug
+
+## Running
+
+**Windows / Linux**
+
+* Pass the disc image as a positional argument using the `--dvd` flag. Supported formats are: ISO (GCM), RVZ, WIA, WBFS, CISO, GCZ
+
 ```sh
-build/{preset}/dusklight/path/to/game.rvz
+build/{preset}/dusklight --dvd /path/to/game.iso
+```
+
+**macOS**
+
+macOS builds an `.app` bundle which contains the executable and all necessary resources.
+
+* Pass the disc image as a positional argument using the `--dvd` flag. Supported formats are: ISO (GCM), RVZ, WIA, WBFS, CISO, GCZ
+
+```sh
+build/{preset}/Dusklight.app/Contents/MacOS/Dusklight --dvd /path/to/game.iso
 ```
-If no path is specified, Dusklight defaults to `game.iso` in the current working directory.