Windcorp/Progressia
3
0
Fork 0
mirror of https://gitea.windcorp.ru/Wind-Corporation/Progressia.git synced 2025-06-09 01:20:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

TMP / Updated guides

Browse Source
This commit is contained in:
OLEGSHA 2023-11-10 19:57:34 +01:00
parent c095e4a049
commit d8907afcd5
No known key found for this signature in database
GPG Key ID: 4BB0CC24939DB485
2 changed files with 129 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/BuildingGuide.md
View File

@ -1,32 +1,25 @@
# Building Guide
This document provides instructions for building Progressia from source code.
This document provides instructions for building Progressia from source code.
See also
[Development Setup Guide](DevelopmentSetupGuide.md)
and
[IDE setup guides](TODO).
[IDE setup guides](ide_setup).
MacOS targets are not supported at this moment.
## Short version
Debian/Ubuntu:
```bash
# Install GCC, CMake, Python 3, git, Vulkan, GLFW and GLM
# Install GCC, CMake, Python 3, glslc, 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; )
g++ cmake python3 glslc git libvulkan-dev libglfw3-dev libglm-dev
# Clone project
git clone CLONE-URL
git clone https://github.com/Wind-Corporation/Progressia.git
cd Progressia
# Generate build files for release
# Generate build files for release (MY-1 is the build ID)
cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release
# Compile
@ -38,14 +31,15 @@ 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
# Install GCC, CMake, Python 3, glslc, git, Vulkan, GLFW and GLM
sudo dnf install -y \
gcc-c++ cmake python3 glslc git vulkan-devel glfw-devel glm-devel
# Clone project
git clone CLONE-URL
git clone https://github.com/Wind-Corporation/Progressia.git
cd Progressia
# Generate build files for release
# Generate build files for release (MY-1 is the build ID)
cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release
# Compile
@ -55,21 +49,21 @@ cmake --build build
build/progressia
```
Windows: _see [IDE setup guides](TODO)._
Windows: _see [IDE setup guides](ide_setup)._
## Prerequisites
### C++ compiler
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.
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.
On Windows,
[w64devkit](https://github.com/skeeto/w64devkit/releases)
distribution of MinGW was tested.
Cross-compilation from Linux to Windows is also explicitly supported with
Cross-compilation from Linux to Windows is also explicitly supported with
MinGW-w64 as provided by Debian.
### CMake
@ -85,43 +79,50 @@ MinGW-w64 as provided by Debian.
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))
- `glslc` ([standalone downloads](https://github.com/google/shaderc/blob/main/downloads.md))
However, it is usually easier to install a complete Vulkan SDK. An open-source
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:
Debian/Ubuntu users can install this dependency using APT:
```bash
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; )
apt install libvulkan-dev glslc
```
Ubuntu dpkg packages are available from LunarG.
Fedora users can install Vulkan using dnf:
Fedora users can install this dependency using dnf:
```bash
dnf install vulkan-devel glslc
```
Windows users using vcpkg should install the LunarG distribution, then install
the `vulkan` vcpkg package:
```cmd
vcpkg install vulkan:x64-mingw-static
```
### Other libraries
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/)
Debian/Ubuntu users can install these dependencies using APT:
```bash
apt install libglfw3-dev libglm-dev
```
Fedora users can install these dependencies using dnf:
```bash
dnf install glfw-devel glm-devel
```
Windows users can install these dependencies using vcpkg:
```cmd
vcpkg install glfw3:x64-mingw-static glm:x64-mingw-static
```
## Downloading source code
Clone this git repository.
@ -136,16 +137,16 @@ git clone <clone url>
### CMake
Use CMake to generate build files. There are a few options available:
- **`BUILD_ID`** enables release builds and specifies visible unique build
- **`BUILD_ID`** enables release builds and specifies visible unique build
identifier string.
- `DEV_MODE` enables developer features.
See [Development Setup Guide](DevelopmentSetupGuide.md).
- `DEV_MODE`, `VULKAN_ERROR_CHECKING`:
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
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.
Directory `build` in project root is ignored by git for convenience.
This step is usually performed in the IDE.
@ -160,7 +161,7 @@ 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
> 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.
@ -187,5 +188,5 @@ cmake --build build
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.
Directory `run` in project root is ignored by git for convenience; using
project root as working directory is safe for debug builds.

126
docs/DevelopmentSetupGuide.md
View File

@ -1,63 +1,93 @@
# Development setup guide
To make development easier, contributors should be using a few tools. Included
with the project are configurations and scripts for these tools:
- [cppcheck](http://cppcheck.net/) – performs static code analysis for C++
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) – automatically
formats C++ source code
- [memcheck](https://valgrind.org/docs/manual/mc-manual.html)
(part of [valgrind](https://valgrind.org/)) – performs runtime memory
error detection
This document provides instructions for setting up a development environment
for Progressia.
See also
[Building Guide](BuildingGuide.md)
and
[IDE setup guides](ide_setup).
Additionally, git hooks prevent committing code that is formatted incorrectly,
does not compile or produces warnings. You can bypass this check using
To make development easier, contributors should be using a few tools. Included
with the project are configurations and scripts for these tools:
- [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) – performs static
code analysis for C++
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) – formats C++
source code
- Vulkan validation layers – checks for errors in Vulkan API usage at runtime
(see below for details)
- [memcheck](https://valgrind.org/docs/manual/mc-manual.html)
(part of [valgrind](https://valgrind.org/)) – performs runtime memory
error detection on Linux
Additionally, a git pre-commit hook prevents committing code that is formatted
incorrectly, does not compile or produces warnings.
## Basic setup
Follow [Building Guide](BuildingGuide.md) instructions before proceeding.
Debian/Ubuntu:
```bash
# Install clang-tidy and clang-format-diff
sudo apt update && sudo apt install -y \
clang-tidy clang-format
# Enable DEV_MODE (sets up git pre-commit hook)
cmake -S . -B build -DDEV_MODE=ON
```
Fedora:
```bash
# Install clang-tidy and clang-format-diff
sudo dnf install -y \
clang-tools-extra clang
# Enable DEV_MODE (sets up git pre-commit hook)
cmake -S . -B build -DDEV_MODE=ON
```
Windows: _see [IDE setup guides](ide_setup)._
## Pre-commit git hook
A
[git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
is installed to correct formatting and check for compilation/linting issues.
This check can be bypassed with
`git commit --no-verify`
in case of dire need.
## Prerequisites
The hook runs `tools/pre-commit.py`, which formats modified files and ensures
that `cmake --build build` executes without errors. Several git operations are
performed by `pre-commit.py`; run
`tools/pre-commit.py restore`
to restore the state of the repository in case the hook crashes.
Perform the setup described in the [Building Guide](BuildingGuide.md) first.
The list of directories with source code to format and the list of source code
filename extensions are hard-coded into the Python script.
Install the following software:
- cppcheck,
- clang-format (version 13 is recommended)
- valgrind
## Vulkan validation layers
### Debian
On Debian, you can run the following commands as root to install all required
software:
```bash
apt-get install \
cppcheck \
clang-format-13 \
valgrind
```
## Setup
```bash
tools/setup.sh --for-development
```
With `--for-development` flag, `tools/setup.sh` will check the development tools
and install git pre-commit hook in addition to its normal duties.
## Notes
Developers will find it useful to read through the following help pages:
```bash
tools/build.sh --help
tools/cppcheck/use-cppcheck.sh --help
tools/clang-format/use-clang-format.sh --help
```
LunarG validation layers are extremely useful when writing and debugging Vulkan.
LunarG validation layers are extremely useful when debugging Vulkan code.
The official
[Vulkan tutorial](https://vulkan-tutorial.com/Development_environment)
has detailed instructions for all platforms.
In particular, Debian users can run the following command as root:
Use CMake option `VULKAN_ERROR_CHECKING` to enable the use of validation
layers.
Debian/Ubuntu users can install this dependency using APT:
```bash
apt-get install vulkan-validationlayers-dev
apt install vulkan-validationlayers-dev
```
Fedora users can install this dependency using dnf:
```bash
dnf install vulkan-validation-layers-devel
```
Windows users can install this dependency when installing LunarG distribution.
## memcheck
`tools/valgrind-memcheck-suppressions.supp` contains useful suppressions for
memcheck.