Windcorp/Progressia
3
0
Fork 0
mirror of https://gitea.windcorp.ru/Wind-Corporation/Progressia.git synced 2025-08-28 03:26:49 +03:00
Code Issues Packages Projects Releases Wiki Activity

Squash improve-ide-compat into main

Browse Source 
Fixes GH-5

- cppcheck replaced with clang-tidy
- clang-tidy lint warnings fixed
- Reworked build tools from scratch to make IDE setup easier
- Added 1.5 IDE setup guides
This commit is contained in:
OLEGSHA
2023-11-10 21:30:55 +01:00
parent 189d19fd4a
commit ae4e265a90
66 changed files with 2017 additions and 1498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
docs/BuildingGuide.md
View File

@@ -1,85 +1,192 @@
# 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](ide_setup).
MacOS targets are not supported at this moment.
## Short version
Debian/Ubuntu:
```bash
# Install GCC, CMake, Python 3, glslc, git, Vulkan, GLFW and GLM
sudo apt update && sudo apt install -y \
g++ cmake python3 glslc git libvulkan-dev libglfw3-dev libglm-dev
# Clone project
git clone https://github.com/Wind-Corporation/Progressia.git
cd Progressia
# Generate build files for release (MY-1 is the build ID)
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, 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 https://github.com/Wind-Corporation/Progressia.git
cd Progressia
# Generate build files for release (MY-1 is the build ID)
cmake -S . -B build -DBUILD_ID=MY-1 -DCMAKE_BUILD_TYPE=Release
# Compile
cmake --build build
# Run
build/progressia
```
Windows: _see [IDE setup guides](ide_setup)._
## 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](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/Ubuntu 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 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:
Fedora users can install this dependency 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`.
Windows users using vcpkg should install the LunarG distribution, then install
the `vulkan` vcpkg package:
```cmd
vcpkg install vulkan:x64-mingw-static
```
## Setup
### 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.
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`, `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
package).
Directory `build` in project root is ignored by git for 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 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.

100
docs/ide_setup/WindowsCLion.md Normal file
View File

@@ -0,0 +1,100 @@
# IDE setup guide: Windows / CLion
> **Note**
>
> This guide has not been tested sufficiently because currently none of the
> developers use CLion to develop Progressia. Please let us know if this guide
> requires corrections or updates.
This document is an IDE setup guide for CLion with MinGW, the recommended
compiler for Windows.
Compilation with MSVC and clang-cl is supported; however, these compilers may
generate warnings. Additionally, release builds compiled with MSVC or clang-cl
are strongly discouraged, see [Building Guide](../BuildingGuide.md).
## Installing CLion
Install CLion as usual. Close CLion for the following steps.
> **Note**
>
> Native vcpkg support has been added to CLion in version 2023.1. At the time
> of writing this is a recent update. Make sure you use the latest version.
>
> Workaround for older versions: add
> `-DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake`
> to CMake options.
## Installing build tools
### Python 3
Install Python 3 (available from
[the official website](https://www.python.org/downloads/)
and Microsoft Store). Make sure `python` or `python3` is available in PATH:
```cmd
:: This command must work in a fresh CMD:
python3 --version
```
Note that if running this command launches Microsoft Store, Python was not
installed correctly.
### MinGW
Install MinGW. There are many distributions of MinGW available; this guide was
tested with [w64devkit](https://github.com/skeeto/w64devkit).
To install w64devkit, go to the
[Releases](https://github.com/skeeto/w64devkit/releases)
section of the official repository. Download the `w64devkit-XXX.zip` file and
extract it into `C:\msys64\mingw64\`. If extracted correctly,
`C:\msys64\mingw64\bin\gcc.exe`
should exist. Directory
`C:\msys64\mingw64\bin\`
should be added to system PATH
([instructions for Windows 10](https://stackoverflow.com/a/44272417/4463352)).
Proper installation can be verified like so:
```cmd
:: This command must work in a fresh CMD:
gcc --version
```
## Installing libraries
Several third party libraries are used by the project. With Windows, installing
them manually can be a hassle, so the developers recommend using vcpkg.
A Vulkan SDK has to be installed before vcpkg can install `vulkan` package.
[LunarG](https://www.lunarg.com/vulkan-sdk/) distribution is recommended:
download and run the SDK installer. "Validation layer" errors are common on
Windows and can usually be safely ignored; they are typically caused by third-
party software such as GPU drivers, OBS or Steam.
To install vcpkg, go to the
[Releases](https://github.com/microsoft/vcpkg/releases) section of the official
repository. Download and extract "Source code" ZIP file to a directory of your
choice. Run the following commands inside the resulting folder:
```cmd
:: Perform initial setup
bootstrap-vcpkg
:: Setup Visual Studio integration
vcpkg integrate install
:: Install libraries
vcpkg install vulkan:x64-mingw-static glfw3:x64-mingw-static glm:x64-mingw-static
```
## Project setup
Uhm... how do I put it... I could not get my hands on a Windows install of
CLion in a reasonable time and so I will have to leave this blank for now. If
you have CLion on Windows, please contact the devs so we can do the setup
together and this doc can be completed.
In general, from this point you should clone the git repo and open the project
as a CMake project.
## Developer setup
To enable features useful for developers, set CMake option `DEV_MODE` to `ON`.
See [Development Setup Guide](../DevelopmentSetupGuide.md) for more details.

97
docs/ide_setup/WindowsVisualStudio.md Normal file
View File

@@ -0,0 +1,97 @@
# IDE setup guide: Windows / Visual Studio
This document is an IDE setup guide for Visual Studio with MinGW, the
recommended compiler for Windows.
Compilation with MSVC and clang-cl is supported; however, these compilers may
generate warnings. Additionally, release builds compiled with MSVC or clang-cl
are strongly discouraged, see [Building Guide](../BuildingGuide.md).
## Installing Visual Studio
This guide was tested with Visual Studio 2022. "Desktop Development with C++"
workload is required to work with C++ projects. Launch Visual Studio at least
once with this configuration and close it for the next steps.
## Installing build tools
### Python 3
Install Python 3 (available from
[the official website](https://www.python.org/downloads/)
and Microsoft Store). Make sure `python` or `python3` is available in PATH:
```cmd
:: This command must work in a fresh CMD:
python3 --version
```
Note that if running this command launches Microsoft Store, Python was not
installed correctly.
### MinGW
Install MinGW. There are many distributions of MinGW available; this guide was
tested with [w64devkit](https://github.com/skeeto/w64devkit).
To install w64devkit, go to the
[Releases](https://github.com/skeeto/w64devkit/releases)
section of the official repository. Download the `w64devkit-XXX.zip` file and
extract it into `C:\msys64\mingw64\`. If extracted correctly,
`C:\msys64\mingw64\bin\gcc.exe`
should exist. Directory
`C:\msys64\mingw64\bin\`
should be added to system PATH
([instructions for Windows 10](https://stackoverflow.com/a/44272417/4463352)).
Proper installation can be verified like so:
```cmd
:: This command must work in a fresh CMD:
gcc --version
```
## Installing libraries
Several third party libraries are used by the project. With Windows, installing
them manually can be a hassle, so the developers recommend using vcpkg.
A Vulkan SDK has to be installed before vcpkg can install `vulkan` package.
[LunarG](https://www.lunarg.com/vulkan-sdk/) distribution is recommended:
download and run the SDK installer. "Validation layer" errors are common on
Windows and can usually be safely ignored; they are typically caused by third-
party software such as GPU drivers, OBS or Steam.
To install vcpkg, go to the
[Releases](https://github.com/microsoft/vcpkg/releases) section of the official
repository. Download and extract "Source code" ZIP file to a directory of your
choice. Run the following commands inside the resulting folder:
```cmd
:: Perform initial setup
bootstrap-vcpkg
:: Setup Visual Studio integration
vcpkg integrate install
:: Install libraries
vcpkg install vulkan:x64-mingw-static glfw3:x64-mingw-static glm:x64-mingw-static
```
## Project setup
Start Visual Studio. Use "Clone a Repository" to download sources and create a
project. Select the project in Solution Explorer and wait for CMake
initialization to complete.
Next, click on "x64-Debug" in the toolbar. Click on "Manage Configurations..."
to open CMake Settings. Use the plus button to add a new configuration; select
"Mingw64-Debug" when prompted. Select the new configuration and add the
following parameter to "CMake command arguments":
```
-DVCPKG_TARGET_TRIPLET=x64-mingw-static
```
Remove "x64-Debug" configuration by selecting it and pressing the cross button.
Finally click "▶ Select startup item" in the toolbar and choose progressia.exe.
## Developer setup
To enable features useful for developers, set CMake option `DEV_MODE` to `ON`.
See [Development Setup Guide](../DevelopmentSetupGuide.md) for more details.
TODO: _include step-by-step instructions for this section._