From 38e5332b90217efab536d03bfb271e000ab693ae Mon Sep 17 00:00:00 2001 From: Jason Yundt Date: Sun, 26 May 2024 14:45:04 -0400 Subject: [PATCH] Revamp build instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before this change was made, I had tried building Descent 3 on Windows for the first time. The instructions for building Descent 3 on Windows were unclear, inaccurate and they messed up my installation of Windows. (See #332 for details). I started working on this commit in order to prevent that situation from happening again. I ended up revamping the entire build instructions section. The biggest change that I made was making it so that users only need to look at the instructions for their own platforms. Before this change, you had to look at the “Building” heading and read the sentence that was directly beneath it. If you don’t do what that sentence says, then the instructions won’t work. Unfortunately, the way that the instructions were laid out drew the reader’s eye away from that sentence. Specifically, the instructions would draw the reader’s attention towards the subheading for their specific platform. This commit makes it so that each platform-specific subsection contains everything that users of that platform need to know. Another change that I made has to do with Git. Previously, the instructions said “Build steps below assume you have already cloned the repository and entered it locally.” They never told users how to make sure that Git is installed or how to create a clone of the repository. They also didn’t tell Windows users that the clone of Descent3 should not be entered until after VCPKG_ROOT has been set. In other words, if a Windows user had followed the instructions exactly as they were written, then they would have ended up with a clone of vcpkg inside of their clone of Descent3 (not using submodules!). This commit adds explicit instructions for installing Git and cloning Descent3. It also makes sure that Descent3 is only cloned after all dependencies have been installed. I also made a Visual Studio-related changes in this commit. Previously, the instructions for Windows said “Requires Visual Studio 2022 and C++ Tools (cmake and vcpkg)”, but the instructions never told users how to make sure that they had those things. This commit adds explicit instructions for how to make sure that you have Visual Studio and the required components installed. Another change that this commit makes has to do with vcpkg. Before this commit, the Windows build instructions had you manually set up vcpkg. This was redundant because the instructions also had you install Visual Studio 2022 with the “Desktop development with C++” workload. That workload comes with vcpkg [1], so setting up vcpkg manually was unnecessary. This commit removes the parts about installing vcpkg. (Thanks to @Lgt2x for this idea [2].) The commit also adds sentences to the ends of the platform-specific build instructions that tell users where the built files get put. This is technically redundant since the Usage instructions already tell users where to find the built files. Even though those sentences are redundant, I still included them because they make the instructions easier to use. This commit also makes a minor capitalization-related change. Previously, the build instructions said “Building - MacOS”. The official capitalization has been “macOS” since 2016 [3][4]. Another minor change that this commit makes has to do with the Ubuntu and Fedora build instructions. This commit adds the sentence “Run these commands:” to each of those sections. I only added that sentence in order to make the Ubuntu and Fedora sections more consistent with the Windows and macOS sections. The Windows and macOS sections use that sentence as part of a numbered list. [1]: [2]: [3]: [4]: --- README.md | 81 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index cd2048acb..41aee876e 100644 --- a/README.md +++ b/README.md @@ -92,47 +92,82 @@ The milestone needs testing on all platforms. Please report issues when found. - D3 Open Source compiles level scripts in their own hogfiles. Make sure you copy and overwrite `d3-{platform}.hog`. ## Building -Build steps below assume you have already cloned the repository and entered it locally. - #### Building - Windows -Requires Visual Studio 2022 and C++ Tools (cmake and vcpkg) +1. Make sure that you have Git and Visual Studio 2022 with the “Desktop development with C++” workload. If you don’t already have those installed or you aren’t sure, then open an elevated Command Prompt and run: -Install and configure vcpkg: -```sh -git clone https://github.com/microsoft/vcpkg.git -cd vcpkg && bootstrap-vcpkg.bat -setx VCPKG_ROOT="C:\path\to\vcpkg" -setx PATH=%VCPKG_ROOT%;%PATH% -``` + -#### Building - MacOS -```sh -brew bundle install -cmake --preset mac -D ENABLE_LOGGER=[ON|OFF] -cmake --build --preset mac --config [Debug|Release] -``` + ```batch + winget install Git.Git Microsoft.VisualStudio.2022.Community + + "%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\setup.exe" modify^ + --passive^ + --channelId VisualStudio.17.Release^ + --productId Microsoft.VisualStudio.Product.Community^ + --add Microsoft.VisualStudio.Workload.NativeDesktop;includeRecommended + ``` + +2. Open a “x86 Native Tools Command Prompt” and run: + + ```batch + git clone https://github.com/DescentDevelopers/Descent3 + cd Descent3 + cmake --preset win32 -D ENABLE_LOGGER=[ON|OFF] + cmake --build --preset win32 --config [Debug|Release] + ``` + +Once CMake finishes, the built files will be put in `builds\win32\Descent3\Debug` or `builds\win32\Descent3\Release`. + +#### Building - macOS +1. Make sure that [Xcode](https://developer.apple.com/xcode) is installed. + +2. Make sure that [Homebrew](https://brew.sh) is installed. + +3. Run these commands: + + ```sh + git clone https://github.com/DescentDevelopers/Descent3 + cd Descent3 + brew bundle install + cmake --preset mac -D ENABLE_LOGGER=[ON|OFF] + cmake --build --preset mac --config [Debug|Release] + ``` + +Once CMake finishes, the built files will be put in `builds/mac/Descent3/Debug` or `builds/mac/Descent3/Release`. #### Building - Linux (Ubuntu) +Run these commands: + ```sh sudo apt update -sudo apt install -y --no-install-recommends ninja-build cmake g++ libsdl2-dev zlib1g-dev +sudo apt install -y --no-install-recommends git ninja-build cmake g++ libsdl2-dev zlib1g-dev +git clone https://github.com/DescentDevelopers/Descent3 +cd Descent3 cmake --preset linux -D ENABLE_LOGGER=[ON|OFF] cmake --build --preset linux --config [Debug|Release] ``` +Once CMake finishes, the built files will be put in `builds/linux/Descent3/Debug` or `builds/linux/Descent3/Release`. + #### Building - Linux (Fedora) +Run these commands: + ```sh sudo dnf update --refresh -sudo dnf install -y ninja-build cmake gcc-c++ SDL2-devel zlib-devel +sudo dnf install -y git ninja-build cmake gcc-c++ SDL2-devel zlib-devel +git clone https://github.com/DescentDevelopers/Descent3 +cd Descent3 cmake --preset linux -D ENABLE_LOGGER=[ON|OFF] cmake --build --preset linux --config [Debug|Release] ``` +Once CMake finishes, the built files will be put in `builds/linux/Descent3/Debug` or `builds/linux/Descent3/Release`. + ## Contributing Anyone can contribute! We have an active Discord presence at [Descent Developer Network](https://discord.gg/GNy5CUQ). If you are interested in maintaining the project on a regular basis, please contact Kevin Bentley.