Flecs: Building Flecs
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Building Flecs

This manual describes how to compile the Flecs source code.

# Dependencies

The following libraries need to be linked when building Flecs:

- Windows

  Library | Used by | Used for
  --- | --- | ---
  dbghelp | Core | Logging stack traces
  ws2_32 | HTTP addon | Allows explorer to connect

- Linux

  Library | Used by | Used for
  --- | --- | ---
  rt | Core | Time functions
  pthread | OS_API addon | Threading functions
  m | Core | Math functions

- MacOS

  No dependencies required on MacOS.

# Build with distr files

The easiest way to add Flecs to a project is to add the distr/flecs.c and distr/flecs.h files to the project source. When building, make sure your build system is setup to do the following:

- If it is a C++ project, make sure to compile distr/flecs.c as C code, for example by using gcc/clang instead of g++/clang++.
- If you are building on Windows and you're not using the Microsoft Visual Studio compiler, make sure to add -lws2_32 -ldbghelp to the end of the linker command.
- When compiling Flecs with gcc/clang, add -std=gnu99 to the compiler command. This ensures that addons that rely on time & socket functions are compiled correctly.
- C++ files that use Flecs must be compiled with -std=c++17 or higher.

## Command line examples

These examples are just for illustration. For most projects it is recommended to use a build system like cmake, bazel or bake.

- Windows

  Clang, C

  clang my_project.c -c -o my_project.o
  clang flecs.c -c -o flecs.o
  clang my_project.o flecs.o -ldbghelp -lws2_32 -o my_project

  Clang, C++

  clang++ my_project.cpp -std=c++17 -c -o my_project.o
  clang flecs.c -c -o flecs.o
  clang++ my_project.o flecs.o -ldbghelp -lws2_32 -o my_project

  MSVC, C

  cl /nologo /c my_project.c /Fo:my_project.obj
  cl /nologo /c flecs.c /Fo:flecs.obj
  cl /nologo my_project.obj flecs.obj dbghelp.lib ws2_32.lib /Fe:my_project.exe

  MSVC, C++

  cl /nologo /EHsc /c my_project.cpp /Fo:my_project.obj
  cl /nologo /TC /c flecs.c /Fo:flecs.obj
  cl /nologo my_project.obj flecs.obj dbghelp.lib ws2_32.lib /Fe:my_project.exe

- Linux

  GCC, C

  gcc my_project.c -std=gnu99 -c -o my_project.o
  gcc flecs.c -std=gnu99 -c -o flecs.o
  gcc my_project.o flecs.o -lrt -lpthread -lm -o my_project

  GCC, C++

  g++ my_project.cpp -std=c++17 -c -o my_project.o
  gcc flecs.c -std=gnu99 -c -o flecs.o
  g++ my_project.o flecs.o -lrt -lpthread -lm -o my_project

  Clang, C

  clang my_project.c -std=gnu99 -c -o my_project.o
  clang flecs.c -std=gnu99 -c -o flecs.o
  clang my_project.o flecs.o -lrt -lpthread -lm -o my_project

  Clang, C++

  clang++ my_project.cpp -std=c++17 -c -o my_project.o
  clang flecs.c -std=gnu99 -c -o flecs.o
  clang++ my_project.o flecs.o -lrt -lpthread -lm -o my_project

- Macos

  Clang, C

  clang my_project.c -std=gnu99 -c -o my_project.o
  clang flecs.c -std=gnu99 -c -o flecs.o
  clang my_project.o flecs.o -o my_project

  Clang, C++

  clang++ my_project.cpp -std=c++17 -c -o my_project.o
  clang flecs.c -std=gnu99 -c -o flecs.o
  clang++ my_project.o flecs.o -o my_project

## Build as shared library

To build the distr/flecs.c and distr/flecs.h files as a shared library, remove this line from the top of flecs.h:

#define flecs_STATIC

When compiling distr/flecs.c, make sure to define flecs_EXPORTS, for example by adding -Dflecs_EXPORTS to the compiler command. This ensures that Flecs symbols are exported.

The following example shows how to create a shared library using flecs.c and flecs.h with clang on Linux:

clang flecs.c -c -Dflecs_EXPORTS -o flecs.o
clang flecs.o -lrt -lpthread -lm -shared -o libflecs.so

# Updating the distr files

If you've made a modification to the Flecs source code (in the src or include folders) and you want to update the flecs.c and flecs.h files in the distr folder, run bake once in the root of the repository:

bake

Make sure that the files in distr now have your modifications. If they have not been updated, it's possible that the date of the files is newer than your modifications. If this happens, remove the distr folder and run bake again. This will regenerate files with the latest modifications.

It is not recommended to modify the flecs.c and flecs.h directly.

# Build from source

This will build the files in src and include with one of the following build systems:

## Cmake

Run this command in the repository root to create flecs library binaries:

cmake -S . -B cmake_build && cmake --build cmake_build

After the command finishes, the cmake_build folder will contain one static and one dynamic library binary.

You can also add the Flecs repository as dependency for another cmake project by adding the following line to the CMakeLists.txt of the project:

add_subdirectory(external/flecs)

Alternatively, you can use FetchContent to automatically download Flecs:

include(FetchContent)
FetchContent_Declare(
flecs
GIT_REPOSITORY https://github.com/SanderMertens/flecs.git
GIT_TAG master
)
FetchContent_MakeAvailable(flecs)

Then to link with flecs, add the following to CMakeLists.txt:

target_link_libraries(${PROJECT_NAME} flecs::flecs_static)

## Meson

To build Flecs with meson, run the following commands in the repository root:

meson meson_build
cd meson_build
meson compile

## Bazel

To build Flecs with bazel, run the following command in the repository root:

bazel build //:flecs

## Bake

To build Flecs with bake, run the following command in the repository root:

bake

After this Flecs should show up in the bake environment when doing:

bake list

To create a new Flecs C project, do:

bake new my_project -t flecs

To create a new Flecs C++ project, do:

bake new my_project -t flecs --language c++

To run the project, do:

cd my_project
bake run

# Building the documentation

To generate the HTML version of the documentation, run the following command:

doxygen docs/cfg/Doxyfile

The generated HTML files will be written to docs/html.

# Running the test suite

Flecs uses the test framework that ships with bake. While it is possible to run tests with other build systems, it is recommended to use bake.

## Bake

Make sure to at least build flecs once, by running this in the repository root:

bake

Make sure that Flecs is listed in the bake environment by doing:

bake list

Then run the command for the test project you want to run:

bake run test/core
bake run test/addons
bake run test/query
bake run test/meta
bake run test/script
bake run test/cpp
bake run test/collections

To run a single test suite, do:

bake run test/core -- Sparse

To run a single test case, do:

bake run test/core -- Sparse.get

Some test suites are parameterized. To provide a value for a parameter, do:

bake run test/core - Sparse --param fragment=no

You can specify the number of threads with -j (default is 4):

bake run test/core -- -j 10

To add a new test case, first add it to the project.json of the project you want to add it to, for example:

"testcases": [
// existing test cases...
"my_new_testcase"
]

Then build the test project once:

bake test/core

The suite to which you added the test case will now have an empty test function:

void Sparse_my_test_case(void) {
// Implement testcase
}

When running the test suite now you will see:

EMPTY Sparse.my_test_case (add test statements)
To run/debug your test, do:
export $(bake env)
test/core/bin/arm64-Darwin-debug/core Sparse.my_test_case --param fragment=yes

This indicates that the test case isn't testing anything yet. Add one or more test_assert (or equivalent) calls to the code to make this message go away.

## Cmake (experimental)

First make sure to clone bake.

Run the following commands to run all the tests:

# Generate make files for Flecs and tests
cmake -DFLECS_TESTS=ON -DBAKE_DIRECTORY="path to cloned bake repository"
# Build flecs and test suites
cmake --build . -j 4
# Run the tests
ctest -C Debug --verbose

## Bazel (experimental)

Run the following commands to run all the tests:

bazel build //:flecs
bazel test --test_output=all //test/...

# Building on Emscripten

When building for emscripten, add the following command line options to the emcc link command:

-s ALLOW_MEMORY_GROWTH=1
-s STACK_SIZE=1mb
-s EXPORTED_RUNTIME_METHODS=cwrap
-s MODULARIZE=1
-s EXPORT_NAME="my_app"

# Building on Android

When building for Android, you should:

- download NDK
- check the cmake preset file and update the cacheVariables as you like
- run a command like below:

cmake -S. -Bbuild_android -GNinja --preset=Android

Then run command ninja in build_android directory to start build.

# Addons

Flecs has a modular architecture that makes it easy to only build the features you really need. By default all addons are built. To customize a build, first define FLECS_CUSTOM_BUILD, then add defines for the addons you need. For example:

#define FLECS_CUSTOM_BUILD // Don't build all addons
#define FLECS_SYSTEM // Build FLECS_SYSTEM

Additionally, you can also specify addons to exclude from a build by adding NO to the define:

#define FLECS_NO_LOG

The following addons can be configured:

Addon | Description | Define
--- | --- | ---
Cpp | C++17 API | FLECS_CPP
Module | Organize game logic into reusable modules | FLECS_MODULE
System | Create & run systems | FLECS_SYSTEM
Pipeline | Automatically schedule & multithread systems | FLECS_PIPELINE
Timer | Run systems at time intervals or at a rate | FLECS_TIMER
Meta | Flecs reflection system | FLECS_META
Units | Builtin unit types | FLECS_UNITS
JSON | JSON format | FLECS_JSON
Doc | Add documentation to components, systems & more | FLECS_DOC
Http | Tiny HTTP server for processing simple requests | FLECS_HTTP
Rest | REST API for showing entities in the browser | FLECS_REST
Parser | Parser utilities used by script & query DSL | FLECS_PARSER
Query DSL | Query DSL parser | FLECS_QUERY_DSL
Script | DSL for scenes, assets and configuration | FLECS_SCRIPT
Stats | Functions for collecting statistics | FLECS_STATS
Metrics | Create metrics from user-defined components | FLECS_METRICS
Alerts | Create alerts from user-defined queries | FLECS_ALERTS
Log | Extended tracing and error logging | FLECS_LOG
Journal | Journaling of API functions | FLECS_JOURNAL
App | Flecs application framework | FLECS_APP
OS API Impl | Default OS API implementation for Posix/Win32 | FLECS_OS_API_IMPL

The following example shows how to build Flecs without any addons using bake. Run the command from the repository root:

bake -D FLECS_CUSTOM_BUILD

To only build Flecs with the system addon, do:

bake -D FLECS_CUSTOM_BUILD -D FLECS_SYSTEM

The following example shows how to build Flecs without any addons using clang:

clang my_project.c -std=gnu99 -c -o my_project.o
clang flecs.c -DFLECS_CUSTOM_BUILD -std=gnu99 -c -o flecs.o
clang my_project.o flecs.o -lrt -lpthread -lm -o my_project

To only build Flecs with clang with the system addon, do:

clang my_project.c -std=gnu99 -c -o my_project.o
clang flecs.c -DFLECS_CUSTOM_BUILD -DFLECS_SYSTEM -std=gnu99 -c -o flecs.o
clang my_project.o flecs.o -lrt -lpthread -lm -o my_project