building the project¶
using a template¶
This projects provides a ready to use template with all required dependencies preconfigured. It can be used in two ways, either by creating your own copy (recommended) or by cloning it directly.
a. creating a copy
Go to josekoalas/mermelada and click on the green button that says "Use this template". This requires a GitHub account. You will be taken to a new screen to configure the new repository settings. Set a name and the options you prefer and click on "Create repository from template". Now you will have a copy of the template in your profile ready to use. Download it with the following command, replacing your_github_username
and repository_name
with the appropiate values.
git clone --recurse-submodules https://github.com/your_github_username/repository_name
cd repository_name
b. cloning the template
If you don't have a github account or you don't want to create a copy, you can download the template directly by doing:
git clone --recurse-submodules https://github.com/josekoalas/mermelada
cd mermelada
building the project¶
The template repository already includes a CMakeLists.txt
with all the configuration needed. Please ensure you have a compatible compiler and a recent version of cmake and the vulkan sdk before proceeding. To configure and build the project use the following two commands respectively:
cmake -S . -B build
cmake --build build
tested compilers¶
These compilers have been tested to work. Older versions might work but are not officially supported.
- clang 14.0+
- apple clang 14.0+
- gcc 12.1+
MSVC is mostly working, except for nested constexpr for loops in the math library. There is an issue where these loops don't compile only with MSVC. I already submitted a bug report with a temporary workaround, and it is pending release. At this time, clang or gcc are recommended.
When building for macos and using gcc, please note that you have to use apple clang as the c compiler and g++ as the c++ compiler, since gcc causes linking error against the developer frameworks when using glfw. See this issue.
On linux systems glfw requires some development libraries. For X11 and debian you should be fine using sudo apt install xorg-dev
, for other systems or window managers check the complete list.
extra: installing compilers¶
This is a very brief and general guide to install the most recent compilers. Your system requirements might vary so please refer to the original instructions when in doubt.
debian/ubuntu:
# gcc
apt install build-essential
# clang
apt install clang lldb lld
macos:
If you install XCode or the Command Line Tools it will come with Apple clang. To get the version 14.0, which includes improved support for c++20
, you need to download the beta of XCode 14. Regular clang and gcc can be installed with homebrew:
# gcc
brew install gcc
# clang
brew install llvm
windows:
You can use clang with Visual Studio or install gcc with MinGW. As mentioned above, MSVC is a work in progress.
extra: installing cmake¶
CMake
is our build system of choice. You can download it from the official website or, if you are using an unix like system, get it from a package manager:
debian/ubuntu:
apt install cmake
# or
snap install cmake
macos:
brew install cmake
extra: installing the vulkan sdk¶
Vulkan
is the graphics API we use to render our scenes. It is a very powerful and customizable API that is used by many applications. To develop with Vulkan you need to install the latest version of the Vulkan SDK. There are readily available binaries for all platforms that take care of the installation.
advanced: manual configuration¶
You can ignore the template and add fresa directly into your project. The main library is located in josekoalas/fresa. Please note when adding includes that include directories are specified without the folder, so you have to specify all include files, not just recursive directories. Also make sure that all required libraries are linked propperly.
To use fresa all you need is to include "engine.h" and call fresa::run
. Configuration parameters are a work in progress.
advanced: required libraries¶
- fmt [MIT]: Used for general string formatting, mainly as a basis to the logging system (
log.h
). May be replaced withstd::format
in the future, but it depends on its capabilities.
standard libraries
Some compilers don't have full support of all c++20
features. Therefore, while those compilers get support, you can alternatively use this libraries that the standard is based on as a stand in. Once compiler support is widespread these will be removed.
rendering libraries
Despite incorporating its own renderer, some low level functions are required to create and manage a cross platform window, surface and input. For this purpose we use glfw3, along with glad2 for loading functions for both opengl and vulkan. We also use the vulkan memory allocator for managing memory inside the vulkan application and SPIRV-Cross for shader reflection.
- glfw [ZLIB]: For window creation and input.
- glad [MIT]: For opengl and vulkan loading.
- vma [MIT]: For vulkan memory management.
- spirv-cross [Apache 2.0]: For converting spirv to glsl and reflecting shaders.