Building Guide

This page guides you through the process of creating a custom build of the LiteFX engine, its samples and tests.

Building Guide

You can build the sources on your own. Currently only MSVC and Clang builds under Windows are officially supported. Linux builds (using GCC) are at an experimental stage.

Prerequisites

In order for the project to be built, there are a few prerequisites that need to be present on your environment:

• C++23 compatible compiler: MSVC 17.10, Clang 18.0+ or GCC 14.2. †
• CMake (version 3.23 or higher). ‡
• Optional: LunarG Vulkan SDK 1.3.204.1 or later (required to build the Vulkan backend). When targeting Linux, refer to this guide for setting up the SDK.
• When building for Windows: Windows 10 SDK 10.0.19041.0 or later (required to build DirectX backend).
• When building for Linux: Install dependencies by executing bash dependencies.sh.

† Note that Linux support is currently experimental and implemented on the feature/linux-support branch.

‡ CMake 3.23 is part of Visual Studio 2022 17.3.0 or later. When using other compilers, CMake needs to be installed manually.

Setting up Linux builds

If you want to target Linux, you may want to build GCC 14.2 on your own for the time being, as well as install DXC as an alternative to GLSLC (see below). If you only want to target Windows at the moment, you may skip to the next section.

First, to create a custom build of GCC 14.2 with support for the <stacktrace> library, you can run the following commands:

sudo apt install build-essential
sudo apt install libmpfr-dev libgmp3-dev libmpc-dev -y
wget http://ftp.gnu.org/gnu/gcc/gcc-14.2.0/gcc-14.2.0.tar.gz
tar -xf gcc-14.2.0.tar.gz
cd gcc-14.2.0
./configure -v --build=x86_64-linux-gnu --host=x86_64-linux-gnu --target=x86_64-linux-gnu --prefix=/usr/local/gcc-14.2.0 --enable-libstdcxx-backtrace --enable-checking=release --enable-languages=c,c++ --disable-multilib --program-suffix=-14.2.0
make
sudo make install
sudo update-alternatives --install /usr/bin/g++ g++ /usr/local/gcc-14.2.0/bin/g++14.2.0 14
sudo update-alternatives --install /usr/bin/gcc gcc /usr/local/gcc-14.2.0/bin/gcc14.2.0 14

Next, for DXC you can follow a similar procedure:

mkdir dxc && cd ./dxc/
wget https://github.com/microsoft/DirectXShaderCompiler/releases/download/v1.8.2407/linux_dxc_2024_07_31.x86_64.tar.gz
sudo mkdir /usr/local/dxc
sudo tar -xf linux_dxc_2024_07_31.x86_64.tar.gz -C /usr/local/dxc/
sudo update-alternatives --install /usr/bin/dxc dxc /usr/local/dxc/bin/dxc 2024

Build Process

Create a new directory from where you want to build the sources. Then open your shell and clone the repository:

git clone --recursive https://github.com/crud89/LiteFX.git .

Performing a Build

There are multiple ways of creating a build from scratch. In general, all CMake-based build systems are supported.

From Command Line

Building from command line is the most straightforward way and is typically sufficient, if you only want to consume a fresh build.

cmake src/ --preset windows-msvc-x64-release
cmake --build out/build/windows-msvc-x64-release/ --target install

Using Visual Studio (Windows only)

From Visual Studio open the folder where you just checked out the contents of the repository. In the Project Explorer change the view to CMake Targets. Right click LiteFX and select Install.

Build Customization

You can customize the engine build, according to your specific needs. The most straightforward way is to use CMake presets. Create a file called CMakeUserPresets.json inside the src/ directory and add the following content to it:

{
  "version": 2,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 20,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "win-x64-custom-preset",
      "inherits": "windows-msvc-x64-release",
      "cacheVariables": {
      }
    }
  ]
}

Within the cache variables, you can override the build options, LiteFX exports. All customizable options have the LITEFX_BUILD_ prefix and are described in detail below:

• LITEFX_BUILD_VULKAN_BACKEND (default: ON): builds the Vulkan 🌋 backend (requires LunarG Vulkan SDK 1.3.204.1 or later to be installed on your system).
• LITEFX_BUILD_DX12_BACKEND (default: ON): builds the DirectX 12 ❎ backend.
• LITEFX_BUILD_DEFINE_BUILDERS (default: ON): enables the builder architecture for backends.
• LITEFX_BUILD_SUPPORT_DEBUG_MARKERS (default: OFF): implements support for setting debug regions on device queues.
• LITEFX_BUILD_WITH_GLM (default: ON): adds glm converters to math types. †
• LITEFX_BUILD_WITH_DIRECTX_MATH (default: ON): adds DirectX Math converters to math types. †
• LITEFX_BUILD_HLSL_SHADER_MODEL (default: 6_5): specifies the default HLSL shader model.
• LITEFX_BUILD_EXAMPLES (default: ON): builds the examples. Depending on which backends are built, some may be omitted.
• LITEFX_BUILD_EXAMPLES_DX12_PIX_LOADER (default: ON): enables code that attempts to load the latest version of the PIX GPU capturer in the DirectX 12 samples, if available (and if the command line argument --load-pix=true is specified).
• LITEFX_BUILD_EXAMPLES_RENDERDOC_LOADER (default: OFF): enables code in the samples, that loads the RenderDoc runtime API, if the application is launched from within RenderDoc (and if the command line argument --load-render-doc=true is specified).
• LITEFX_BUILD_TESTS (default: OFF): builds tests for the project.

For example, if you only want to build the Vulkan backend and samples and don't want to use DirectX Math, a preset would look like this:

{
  "version": 2,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 20,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "win-x64-vulkan-only",
      "inherits": "windows-msvc-x64-release",
      "cacheVariables": {
        "LITEFX_BUILD_DX12_BACKEND": "OFF",
        "LITEFX_BUILD_WITH_DIRECTX_MATH": "OFF"
      }
    }
  ]
}

You can build using this preset from command line like so:

cmake src/ --preset win-x64-vulkan-only
cmake --build out/build/win-x64-vulkan-only/ --target install --config Release

† Note that glm and DirectX Math are installed using vcpkg automatically. If one of those options gets disabled, no converters will be generated and the dependency will not be exported. Note that both can be used for DirectX 12 and Vulkan.

Choosing a Shader Compiler

Depending on which backends you want to support, you have to choose a shading language and shader compiler. Refer to the following table for mature differences:

	HLSL	GLSL	HLSL Validation	Target DXIL ❎	Target SPIR-V 🌋
DXC	✔	❌	✔	✔	✔
GLSLC	✔	✔	❌	❌	✔

If you are only ever targeting Vulkan and want to author shaders in GLSL, you can use glslc, which is included in the LunarG Vulkan SDK. Switching to HLSL and DXC allows you to re-use the same shader to target both backends. DXC is also included (since version 1.2.141.0) with support for both, DXIL and SPIR-V code generation and thus should be favored over the DXC binary shipped with the Windows SDK, which only supports targeting DXIL.