TMP / Updated BuildingGuide.md

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
+This document  provides instructions  for building Progressia  from source code.
-X11/Wayland and Windows (cross-compilation). See also
+See also
-[Development Setup Guide](DevelopmentSetupGuide.md)
+    [Development Setup Guide](DevelopmentSetupGuide.md)
-if you want to make git commits.
+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:
+### C++ compiler
-  - a C++ compiler (GCC or clang preferably),
-  - CMake,
-  - Python 3,
-  - glslc.
 
-Install the following libraries with headers:
+Project explicitly fully supports GCC, MinGW and Clang. Compilation with MSVC is
-  - Vulkan (loader library and headers),
+also supported, but it can't be used for release builds and its use is generally
-  - GLFW3,
+discouraged.
-  - GLM,
-  - Boost (only core library required).
 
-### 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
+Cross-compilation  from  Linux  to Windows  is also  explicitly  supported  with
-required software:
+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 \
+apt install libvulkan-dev
-    g++ \
+```
-    cmake \
+However, Debian Bullseye repositories
-    python3 &&
+    [do not include](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=890472)
-apt-get install --no-install-recommends \
+glslc. It  should be installed  manually; see standalone  link above or use this
-    libvulkan-dev \
+script:
-    libglfw3-dev \
+```bash
-    libglm-dev \
+sudo mkdir -p /opt/glslc
-    libboost-dev
+( 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
+Ubuntu dpkg packages are available from LunarG.
-moment. You can install it manually from official sources or use the download it
+
-from windcorp.ru by running these commands as root:
+Fedora users can install Vulkan using dnf:
 ```bash
-apt-get install wget &&
+dnf install vulkan-devel glslc
-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
 ```
 
-Alternatively, packages provided by  LunarG are available for Ubuntu. Follow the
+### Other libraries
-instructions   on  [LunarG.com](https://vulkan.lunarg.com/sdk/home)   to install
-`vulkan-sdk`.
 
-## 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 <clone url>
-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
+Executable file will be located directly inside the CMake binary directory.
-tools/build.sh -R
+
-```
+Directory `run`  in project root  is ignored by git  for builders'  convenience;
+using project root as working directory is safe for debug builds.