Installation¶

CMake FetchContent (recommended)¶

Add the following to your CMakeLists.txt:

cmake_minimum_required(VERSION 3.29)
project(my_project CXX)

set(CMAKE_CXX_STANDARD 26)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)

FetchContent_Declare(
    freyr
    GIT_REPOSITORY https://github.com/gilmar-sales/Freyr.git
    GIT_TAG        main  # pin to a tag or commit SHA for reproducibility
)

FetchContent_MakeAvailable(freyr)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE freyr::freyr)

Then include the single umbrella header:

#include <Freyr/Freyr.hpp>

Building from source¶

git clone --recurse-submodules https://github.com/gilmar-sales/Freyr.git
cd Freyr
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Clone with submodules

Freyr requires Skirnir (fetched automatically via FetchContent by default) and optionally Perfetto (as a git submodule). Use --recurse-submodules to clone the full source tree.

Tests¶

cd build
ctest --output-on-failure

Benchmarks¶

./build/benchmarks/ComponentArray/freyr_component_array_benchmark
./build/benchmarks/ExecutionStrategy/freyr_execution_strategy_benchmark

Build options¶

Standalone (building Freyr from source) defaults:

Option	Default	Description
`FREYR_BUILD_TESTS`	`ON`	Build the test suite
`FREYR_BUILD_BENCHMARKS`	`ON`	Build benchmarks
`FREYR_BUILD_EXAMPLES`	`ON`	Build example applications
`FREYR_ASSERTIONS`	`OFF`	Enable runtime assertions (`FREYR_ASSERT` macro)
`FREYR_PROFILING`	`OFF`	Enable Perfetto tracing support

When Freyr is consumed via FetchContent, tests, benchmarks, examples, and profiling default to OFF.

Pass options via -D on the CMake command line:

cmake -B build -DFREYR_ASSERTIONS=ON -DFREYR_BUILD_BENCHMARKS=ON

Optional: Perfetto profiling¶

Freyr integrates with Perfetto for trace-based profiling. Enable it with the FREYR_PROFILING option. Perfetto is pulled as a git submodule from vendor/perfetto.

cmake -B build -DFREYR_PROFILING=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build --parallel

Profiling build type

Use RelWithDebInfo or Release for profiling. Debug builds have significantly higher overhead and produce distorted timing data.

See the Profiling guide for usage details.

Optional: Enable assertions¶

Runtime assertions help catch programming errors during development:

target_compile_definitions(my_app PRIVATE FREYR_ASSERTIONS)

Alternatively, pass -DFREYR_ASSERTIONS=ON when configuring Freyr itself. Assertions check for:

Component registration before use
Entity ID range validity
Archetype chunk capacity violations

Using with an existing project¶

If you already have a CMakeLists.txt, add Freyr as a dependency:

# In your project's CMakeLists.txt
include(FetchContent)

FetchContent_Declare(
    freyr
    GIT_REPOSITORY https://github.com/gilmar-sales/Freyr.git
    GIT_TAG v1.0.0  # use a specific tag for stability
)

FetchContent_MakeAvailable(freyr)

target_link_libraries(your_target PRIVATE freyr::freyr)

Freyr will automatically find or fetch its own dependencies (Skirnir, Google Test).

Troubleshooting¶

"C++26 not supported"¶

Ensure your compiler supports C++26 reflection (-freflection):

GCC ≥ 16
Clang ≥ 22

"Skirnir not found"¶

Freyr fetches Skirnir via FetchContent automatically. If you have a local copy, set FETCHCONTENT_SOURCE_DIR_SKIRNIR:

cmake -B build -DFETCHCONTENT_SOURCE_DIR_SKIRNIR=/path/to/skirnir

Build is slow¶

Use ccache to cache compilations
Use -j / --parallel with your build tool
Keep FREYR_PROFILING=OFF for day-to-day builds (default)
For development, build only the library: cmake --build build --target freyr