From 31dd069879820fb91f7e94ac723c94a269c8de20 Mon Sep 17 00:00:00 2001 From: Giorgio Mendieta <31053658+GiorgioMendieta@users.noreply.github.com> Date: Sun, 17 May 2026 15:51:38 +0200 Subject: [PATCH] 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 --- docs/building.md | 236 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 183 insertions(+), 53 deletions(-) diff --git a/docs/building.md b/docs/building.md index 1001c42788..9f7879ab48 100644 --- a/docs/building.md +++ b/docs/building.md @@ -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** + +
+Click to expand + +* 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 +``` + +
+
+ +**Arch Linux packages** + +
+Click to expand + +* 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 +``` + +
+
+ +**Fedora packages** + +
+Click to expand + +* 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" +``` + +
+
+ +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.