Getting started

How to download, build and run the engine and where to go from there.

Building the engine from source

Getting the code

The Cubos source code is hosted on GitHub, so the easiest and only way to get the code right now is to clone the repository with git.

Dependencies

The following dependencies are used to compile Cubos:

NameImportanceSubmodule PathInstalled SeparatelyVersion*
CMakeEssential-Yes-
gladEssentialcore/lib/gladNo2.0.4
glfwEssentialcore/lib/glfwOptionally3.3.8
glmEssentialcore/lib/glmOptionally0.9.9.8
stduuidEssentialcore/lib/stduuidNo1.2.3
doctestRequired for testscore/lib/doctestOptionally2.4.11
jsonEssentialcore/lib/jsonNo3.11.2
imguiEssentialengine/lib/imguiNo1.89.9
imguiEssentialengine/lib/implotNo1.89.9

*versions tested in CI and installed by submodules, others might work

Dependencies marked as Essential are required to compile the engine. If they are installed separately, you must first install them manually. If they're not, it means they come as submodules and you can install them with the engine by cloning the whole repository with the --recursive flag. If you've already cloned the repository, you can install them by running the following command from the root directory of the repository:

git submodule update --init --recursive

Formatting

To contribute you must ensure your code is correctly formatted. Install clang-format and run the following command to enable a pre-commit hook which formats your changes automatically:

git config --local include.path ../.gitconfig

Compiling

The easiest way to compile Cubos is by opening its directory in an IDE with CMake support. We recommend using Visual Studio Code with the CMake and C++ extensions installed, as it is cross-platform, and most of the team is using it.

The IDE you choose most probably provides a way to set CMake options through the UI. In Visual Studio Code, you can do this by pressing Ctrl + Shift + P and choosing CMake: Edit CMake Cache (UI). Alternatively, you can change options directly through the CMakeCache.txt on the directory you chose to build the project in (usually build/).

Visual Studio Code's CMake extension allows you to set a build target. You can set this target, for example, to cubos-core, in order to compile only the core. To compile it, just press the build button.

The following is a list of all the options available to configure the engine:

NameDescription
WITH_GLFWUse GLFW? (Required for now)
WITH_OPENGLUse OpenGL? (Required for now)
GLFW_USE_SUBMODULECompile glfw from source?
GLM_USE_SUBMODULECompile glm from source?
DOCTEST_USE_SUBMODULECompile doctest from source?
BUILD_CORE_SAMPLESBuild Cubos core samples?
BUILD_CORE_TESTSBuild Cubos core tests?
BUILD_ENGINE_SAMPLESBuild Cubos engine samples?
BUILD_ENGINE_TESTSBuild Cubos engine tests?
BUILD_DOCUMENTATIONBuild the documentation?
ENABLE_COVERAGEEnable code coverage? (GCC only)
FIX_CLANG_TIDY_ERRORSFix clang-tidy errors automatically?

After you change an option's value, make sure to reconfigure CMake! In Visual Studio Code, you can do this by pressing Ctrl + Shift + P and choosing CMake: Configure.

Running the examples and tests

In Visual Studio Code, the CMake extension allows you to set the debug targets. That target can then by launched/debugged by pressing the launch/debug button.

Examples

Both core and engine contain examples which you can run to check if things are running correctly. To build them, you must enable the BUILD_CORE_SAMPLES and/or BUILD_ENGINE_SAMPLES options. This will show new multiple targets, one for each example.

Testing

Cubos uses doctest for unit testing the engine. To build them, you must enable the BUILD_CORE_TESTS and/or BUILD_ENGINE_TESTS options. You can run the tests through the targets cubos-core-tests and cubos-engine-tests.

Whats next?

We recommend you start by reading the feature guide, which introduces you to important concepts and features of the engine, such as what is an ECS and how it is used in Cubos.

The examples page is also a good place to go if you want to see how specific parts of the engine are used in practice.