From a227556ae36955464c30943575b151f1ebe85d15 Mon Sep 17 00:00:00 2001 From: OLEGSHA Date: Wed, 5 Apr 2023 00:11:09 +0200 Subject: [PATCH] TMP / Updated BuildingGuide.md --- docs/BuildingGuide.md | 224 +++++++++++++++++++++++++++++++----------- 1 file changed, 165 insertions(+), 59 deletions(-) diff --git a/docs/BuildingGuide.md b/docs/BuildingGuide.md index 8c637c5..8bdc0d5 100644 --- a/docs/BuildingGuide.md +++ b/docs/BuildingGuide.md @@ -1,85 +1,191 @@ -# Building guide +# Building Guide -At this time, building is only supported in GNU/Linux targeting GNU/Linux with -X11/Wayland and Windows (cross-compilation). See also -[Development Setup Guide](DevelopmentSetupGuide.md) -if you want to make git commits. +This document provides instructions for building Progressia from source code. +See also + [Development Setup Guide](DevelopmentSetupGuide.md) +and + [IDE setup guides](TODO). + +MacOS targets are not supported at this moment. + +## Short version +Debian/Ubuntu: +```bash +# Install GCC, CMake, Python 3, git, Vulkan, GLFW and GLM +sudo apt update && sudo apt install -y \ + g++ cmake python3 git curl libvulkan-dev libglfw3-dev libglm-dev + +# Install glslc +sudo mkdir -p /opt/glslc +( cd /opt/glslc + sudo curl -LO https://windcorp.ru/other/glslc-v2022.1-6-ga0a247d-static && + sudo chmod +x glslc* && + sudo ln -s glslc* /usr/local/bin/glslc; ) + +# Clone project +git clone CLONE-URL +cd Progressia + +# Generate build files for release +cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release + +# Compile +cmake --build build + +# Run +build/progressia +``` + +Fedora: +```bash +# Install GCC, CMake, Python 3, git, Vulkan, GLFW, GLM and glslc +dnf install -y gcc-c++ cmake python3 git vulkan-devel glfw-devel glm-devel glslc + +# Clone project +git clone CLONE-URL +cd Progressia + +# Generate build files for release +cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release + +# Compile +cmake --build build + +# Run +build/progressia +``` + +Windows: _see [IDE setup guides](TODO)._ ## Prerequisites -Install the following software: - - a C++ compiler (GCC or clang preferably), - - CMake, - - Python 3, - - glslc. +### C++ compiler -Install the following libraries with headers: - - Vulkan (loader library and headers), - - GLFW3, - - GLM, - - Boost (only core library required). +Project explicitly fully supports GCC, MinGW and Clang. Compilation with MSVC is +also supported, but it can't be used for release builds and its use is generally +discouraged. -### Debian +On Windows, + [w64devkit](https://github.com/skeeto/w64devkit/releases) +distribution of MinGW was tested. -On Debian, you can run the following commands as root to install almost all -required software: +Cross-compilation from Linux to Windows is also explicitly supported with +MinGW-w64 as provided by Debian. + +### CMake + +[CMake](https://cmake.org/) version 3.12 or higher is required. + +### Python 3 + +[Python 3](https://www.python.org/downloads/) is required. + +### Vulkan + +The following Vulkan components are strictly necessary for builds: + - Header files + - Loader static library (`vulkan-1.lib`) + - `glslc` (standalone downloads + [here](https://github.com/google/shaderc/blob/main/downloads.md)) + +However, it is usually easier to install a complete Vulkan SDK. An open-source +Vulkan SDK can be downloaded from + [LunarG](https://www.lunarg.com/vulkan-sdk/) +for all platforms. + +Debian users can install this dependency using APT: ```bash -apt-get install \ - g++ \ - cmake \ - python3 && -apt-get install --no-install-recommends \ - libvulkan-dev \ - libglfw3-dev \ - libglm-dev \ - libboost-dev +apt install libvulkan-dev +``` +However, Debian Bullseye repositories + [do not include](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=890472) +glslc. It should be installed manually; see standalone link above or use this +script: +```bash +sudo mkdir -p /opt/glslc +( cd /opt/glslc + sudo curl -LO https://windcorp.ru/other/glslc-v2022.1-6-ga0a247d-static && + sudo chmod +x glslc* && + sudo ln -s glslc* /usr/local/bin/glslc; ) ``` -However, glslc, the shader compiler, is not available as a Debian package at the -moment. You can install it manually from official sources or use the download it -from windcorp.ru by running these commands as root: +Ubuntu dpkg packages are available from LunarG. + +Fedora users can install Vulkan using dnf: ```bash -apt-get install wget && -mkdir -p /opt/glslc && -wget --output-file=/opt/glslc/glslc \ - 'https://windcorp.ru/other/glslc-v2022.1-6-ga0a247d-static' && -chmod +x /opt/glslc/glslc +dnf install vulkan-devel glslc ``` -Alternatively, packages provided by LunarG are available for Ubuntu. Follow the -instructions on [LunarG.com](https://vulkan.lunarg.com/sdk/home) to install -`vulkan-sdk`. +### Other libraries -## Setup +The following libraries are additionally required: + - [GLFW](https://www.glfw.org/download.html) version 3.3.2 or higher + - [GLM](https://glm.g-truc.net/) +## Downloading source code + +Clone this git repository. + +Command line users: run ```bash git clone -cd Progressia -chmod +x tools/setup.sh -tools/setup.sh -``` - -`tools/setup.sh` will check the availability of all required commands and -libraries. - -Build tools use enviroment variables `PATH`, `VULKAN_SDK`, `CMAKE_MODULE_PATH` -and `CMAKE_PREFIX_PATH` to locate the various components; you can edit these -variables system-wide or use `tools/private.sh` to amend them for build tools. -(Your changes to `tools/private.sh` are ignored by git.) -For example, of you ran the script to download glslc on Debian, you will need to -add the following line to `tools/private.sh`: -```bash -PATH="$PATH:/opt/glslc" ``` ## Building +### CMake + +Use CMake to generate build files. There are a few options available: + - **`BUILD_ID`** enables release builds and specifies visible unique build + identifier string. + - `DEV_MODE` enables developer features. + See [Development Setup Guide](DevelopmentSetupGuide.md). + - `VULKAN_ERROR_CHECKING` enables Vulkan debug features. This requires Vulkan + validation layers (available as part of LunarG Vulkan SDK, + `vulkan-validationlayers-dev` Debian package and `vulkan-devel` Fedora + package). + +Directory `build` in project root is ignored by git for builders' convenience. + +This step is usually performed in the IDE. + +Command line users: run ```bash -tools/build.sh +cd /path/to/project +# Routine (debug) build +cmake -S . -B build +# Release build +cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release +``` + +> **Note** +> +> Use proper build IDs if distribution is expected. Convention is two-letter +> builder identifier, a dash and a unique ascending build number. +> +> For example, automated builds at windcorp.ru use IDs `WA-1`, `WA-2`, etc. + +> **Note** +> +> Release builds with MSVC are not supported. +> The standard library used by MSVC poses a problem: +> - it cannot be statically linked with Progressia due to GPL restrictions, +> - it cannot be bundled with Progressia for the same reason, +> - asking the user to install Visual C++ Runtime manually would introduce +> unnecessary confusion because official builds do not require it. + +### Compiling + +This step is usually performed in the IDE. + +Command line users: run +```bash +cmake --build build ``` ## Running -```bash -tools/build.sh -R -``` +Executable file will be located directly inside the CMake binary directory. + +Directory `run` in project root is ignored by git for builders' convenience; +using project root as working directory is safe for debug builds.