Windcorp/Progressia
3
0
Fork 0
mirror of https://gitea.windcorp.ru/Wind-Corporation/Progressia.git synced 2025-06-09 01:10:33 +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 # Building Guide
This document provides instructions for building Progressia from source code. This document provides instructions for building Progressia from source code.
See also See also
[Development Setup Guide](DevelopmentSetupGuide.md) [Development Setup Guide](DevelopmentSetupGuide.md)
and and
[IDE setup guides](TODO). [IDE setup guides](ide_setup).
MacOS targets are not supported at this moment. MacOS targets are not supported at this moment.
## Short version ## Short version
Debian/Ubuntu: Debian/Ubuntu:
```bash ```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 \ sudo apt update && sudo apt install -y \
g++ cmake python3 git curl libvulkan-dev libglfw3-dev libglm-dev g++ cmake python3 glslc git 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 # Clone project
git clone CLONE-URL git clone https://github.com/Wind-Corporation/Progressia.git
cd Progressia 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 cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release
# Compile # Compile
@ -38,14 +31,15 @@ build/progressia
Fedora: Fedora:
```bash ```bash
# Install GCC, CMake, Python 3, git, Vulkan, GLFW, GLM and glslc # Install GCC, CMake, Python 3, glslc, git, Vulkan, GLFW and GLM
dnf install -y gcc-c++ cmake python3 git vulkan-devel glfw-devel glm-devel glslc sudo dnf install -y \
gcc-c++ cmake python3 glslc git vulkan-devel glfw-devel glm-devel
# Clone project # Clone project
git clone CLONE-URL git clone https://github.com/Wind-Corporation/Progressia.git
cd Progressia 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 cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release
# Compile # Compile
@ -55,21 +49,21 @@ cmake --build build
build/progressia build/progressia
``` ```
Windows: _see [IDE setup guides](TODO)._ Windows: _see [IDE setup guides](ide_setup)._
## Prerequisites ## Prerequisites
### C++ compiler ### C++ compiler
Project explicitly fully supports GCC, MinGW and Clang. Compilation with MSVC is Project explicitly fully supports GCC, MinGW and Clang. Compilation with MSVC
also supported, but it can't be used for release builds and its use is generally is also supported, but it can't be used for release builds and its use is
discouraged. generally discouraged.
On Windows, On Windows,
[w64devkit](https://github.com/skeeto/w64devkit/releases) [w64devkit](https://github.com/skeeto/w64devkit/releases)
distribution of MinGW was tested. 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. MinGW-w64 as provided by Debian.
### CMake ### CMake
@ -85,43 +79,50 @@ MinGW-w64 as provided by Debian.
The following Vulkan components are strictly necessary for builds: The following Vulkan components are strictly necessary for builds:
- Header files - Header files
- Loader static library (`vulkan-1.lib`) - Loader static library (`vulkan-1.lib`)
- `glslc` (standalone downloads - `glslc` ([standalone downloads](https://github.com/google/shaderc/blob/main/downloads.md))
[here](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 Vulkan SDK can be downloaded from
[LunarG](https://www.lunarg.com/vulkan-sdk/) [LunarG](https://www.lunarg.com/vulkan-sdk/)
for all platforms. for all platforms.
Debian users can install this dependency using APT: Debian/Ubuntu users can install this dependency using APT:
```bash ```bash
apt install libvulkan-dev apt install libvulkan-dev glslc
```
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; )
``` ```
Ubuntu dpkg packages are available from LunarG. Fedora users can install this dependency using dnf:
Fedora users can install Vulkan using dnf:
```bash ```bash
dnf install vulkan-devel glslc 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 ### Other libraries
The following libraries are additionally required: The following libraries are additionally required:
- [GLFW](https://www.glfw.org/download.html) version 3.3.2 or higher - [GLFW](https://www.glfw.org/download.html) version 3.3.2 or higher
- [GLM](https://glm.g-truc.net/) - [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 ## Downloading source code
Clone this git repository. Clone this git repository.
@ -136,16 +137,16 @@ git clone <clone url>
### CMake ### CMake
Use CMake to generate build files. There are a few options available: 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. identifier string.
- `DEV_MODE` enables developer features. - `DEV_MODE`, `VULKAN_ERROR_CHECKING`:
See [Development Setup Guide](DevelopmentSetupGuide.md). see [Development Setup Guide](DevelopmentSetupGuide.md).
- `VULKAN_ERROR_CHECKING` enables Vulkan debug features. This requires Vulkan - `VULKAN_ERROR_CHECKING` enables Vulkan debug features. This requires Vulkan
validation layers (available as part of LunarG Vulkan SDK, validation layers (available as part of LunarG Vulkan SDK,
`vulkan-validationlayers-dev` Debian package and `vulkan-devel` Fedora `vulkan-validationlayers-dev` Debian package and `vulkan-devel` Fedora
package). 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. 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** > **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. > builder identifier, a dash and a unique ascending build number.
> >
> For example, automated builds at windcorp.ru use IDs `WA-1`, `WA-2`, etc. > 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. Executable file will be located directly inside the CMake binary directory.
Directory `run` in project root is ignored by git for builders' convenience; Directory `run` in project root is ignored by git for convenience; using
using project root as working directory is safe for debug builds. project root as working directory is safe for debug builds.

126
docs/DevelopmentSetupGuide.md
View File

@ -1,63 +1,93 @@
# Development setup guide # Development setup guide
To make development easier, contributors should be using a few tools. Included This document provides instructions for setting up a development environment
with the project are configurations and scripts for these tools: for Progressia.
- [cppcheck](http://cppcheck.net/) – performs static code analysis for C++ See also
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) – automatically [Building Guide](BuildingGuide.md)
formats C++ source code and
- [memcheck](https://valgrind.org/docs/manual/mc-manual.html) [IDE setup guides](ide_setup).
(part of [valgrind](https://valgrind.org/)) – performs runtime memory
error detection
Additionally, git hooks prevent committing code that is formatted incorrectly, To make development easier, contributors should be using a few tools. Included
does not compile or produces warnings. You can bypass this check using 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` `git commit --no-verify`
in case of dire need. 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: ## Vulkan validation layers
- cppcheck,
- clang-format (version 13 is recommended)
- valgrind
### Debian LunarG validation layers are extremely useful when debugging Vulkan code.
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.
The official The official
[Vulkan tutorial](https://vulkan-tutorial.com/Development_environment) [Vulkan tutorial](https://vulkan-tutorial.com/Development_environment)
has detailed instructions for all platforms. 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 ```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.