Progressia/docs/BuildingGuide.md

Building Guide

This document provides instructions for building Progressia from source code. See also Development Setup Guide and IDE setup guides.

MacOS targets are not supported at this moment.

Short version

Debian/Ubuntu:

# 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:

# 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.

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.

On Windows, w64devkit distribution of MinGW was tested.

Cross-compilation from Linux to Windows is also explicitly supported with MinGW-w64 as provided by Debian.

CMake

CMake version 3.12 or higher is required.

Python 3

Python 3 is required.

Vulkan

The following Vulkan components are strictly necessary for builds:

• Header files
• Loader static library (vulkan-1.lib)
• glslc (standalone downloads)

However, it is usually easier to install a complete Vulkan SDK. An open-source Vulkan SDK can be downloaded from LunarG for all platforms.

Debian/Ubuntu users can install this dependency using APT:

apt install libvulkan-dev glslc

Fedora users can install this dependency using dnf:

dnf install vulkan-devel glslc

Windows users using vcpkg should install the LunarG distribution, then install the vulkan vcpkg package:

vcpkg install vulkan:x64-mingw-static

Other libraries

The following libraries are additionally required:

• GLFW version 3.3.2 or higher
• GLM

Debian/Ubuntu users can install these dependencies using APT:

apt install libglfw3-dev libglm-dev

Fedora users can install these dependencies using dnf:

dnf install glfw-devel glm-devel

Windows users can install these dependencies using vcpkg:

vcpkg install glfw3:x64-mingw-static glm:x64-mingw-static

Downloading source code

Clone this git repository.

Command line users: run

git clone <clone url>

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.
• 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

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

cmake --build build

Running

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.