How to build RaZ

RaZ is built with the help of CMake. To generate the project, you must download and install CMake (scroll down to get the latest stable release). If you are on Linux, you had better install it from your package manager.

RaZ can theoretically be compiled with any C++17 compiler. There may be some inconsistencies between compilers, or even between compiler versions, like missing includes; if so, please open an issue or submit a pull request.

At the time of writing, it is tested with (and is assumed to be compatible with any later version of) the following:

• Windows:
  • MinGW-w64 9.3.0 (prior versions from SourceForge are not compatible; those from WinLibs below 9.3.0 are untested)
  • MSVC 14.25
  • Clang-cl 9.0.0
  • Cygwin with Clang 8.0.1
• Linux:
  • GCC 8.4.0
  • Clang 7.0.1
• macOS:
  • Clang 11.0.3
• Emscripten:
  • EmSDK/emcc 1.39.13

Common options

RaZ can be built with several options, depending on the features you need. Any of them can be toggled by appending -DYOUR_OPTION=ON or -DYOUR_OPTION=OFF to your CMake command, or set(YOUR_OPTION ON/OFF CACHE BOOL "" FORCE) in your own CMake file before adding RaZ as a subdirectory.

• RAZ_BUILD_STATIC: build RaZ as a static library; ON by default.
  • ⚠️ Note that at the time of writing, building & using RaZ as a shared library is entirely untested; use it at your own risk.
• RAZ_USE_AUDIO: enable audio capabilities; automatically enabled if OpenAL is found, or with Emscripten which has it built-in.
• RAZ_USE_GLEW: enable GLEW to load OpenGL functions; ON by default. Required to use rendering features; unavailable with Emscripten as it is mandatory.
• RAZ_USE_WINDOW: enable windowing capabilities; ON by default. Required to use rendering features; unavailable with Emscripten as it is mandatory.
• RAZ_USE_IMGUI: enable overlay support; ON by default. Requires RAZ_USE_WINDOW to be enabled.
• RAZ_USE_LUA: enable Lua scripting; ON by default.
• RAZ_USE_FBX: enable FBX file format support; automatically enabled if the FBX SDK is found. Only available under Windows with MSVC or under Linux with GCC.
• RAZ_USE_PROFILING: enable profiling with Tracy; OFF by default.
• RAZ_BUILD_EXAMPLES: declare targets to build & run the examples; ON by default.
• RAZ_BUILD_TESTS: declare a target to build & run the unit tests; ON by default.
• RAZ_FORCE_DEBUG_LOG: force debug logging to be printed even in non-Debug configurations; OFF by default.
• RAZ_ENABLE_COVERAGE: allow coverage to be determined when running tests; OFF by default. Only available under Linux with GCC in the Debug configuration.
• RAZ_GEN_DOC: declare a target to generate the documentation; automatically enabled if Doxygen is found.
• SKIP_RENDERER_ERRORS: remove custom error output from the renderer; OFF by default.
• ENABLE_DEBUG_INFO: declare a target to print "debug" values (platform & compiler info, build configuration, ...); OFF by default.

Building on Windows

Building RaZ requires a C++17-capable compiler (MSVC 19.10 (Visual Studio 2017 15.0), Clang 4/5+, ...). Note that some features used may be supported only by more recent compilers; if RaZ cannot be built due to such a case, please attempt to update your compiler.

Writing in progress.

Building scripting with MinGW

While building the scripting files using MinGW (tested with GCC 11.3 but may occur with previous or following versions), build and especially link times can go through the roof in the default (-O0) Debug mode (up to 13 minutes on my computer). If you need to use scripting in Debug, you are encouraged to set the -Og optimization level, which makes the full build time drop to about 3 minutes; just add -DCMAKE_CXX_FLAGS=-Og when calling CMake.

Building tests with MinGW

Linking time with Catch may be a serious issue, as it can take several minutes to link the unit tests. This seems to happen only with the -O0 flag (thus in Debug mode by default), and is apparently directly related to MinGW.

A seemingly functional workaround for this is to use the lld linker, which can be done by giving the -fuse-ld=lld option to MinGW. This can be done through CMake, by specifying the following command at generation: -DCMAKE_CXX_FLAGS=-fuse-ld=lld.

In some cases, the linking step may also simply fail giving the following error:

Main.cpp.obj: too many sections (35786)
Fatal error: can't write 99 bytes to section .text of Main.cpp.obj: 'file too big'

If that happens, simply add the flag -Wa,-mbig-obj to MinGW: -DCMAKE_CXX_FLAGS="-Wa,-mbig-obj -fuse-ld=lld".

Installation

Installing RaZ on Windows can be made from the RaZ build directory by executing the command cmake --build . --target install.

By default, the install location is C:\RaZ. Feel free to move the installed files wherever you see fit, or directly into the directory you want by modifying the CMAKE_INSTALL_PREFIX variable (beware that depending on the location, you may be required to execute the installation as an administrator).

Building on Linux

Building RaZ requires a C++17-capable compiler (GCC 7+ or Clang 4/5+). Note that some features used may be supported only by more recent compilers; if RaZ cannot be built due to such a case, please attempt to update your compiler.

Writing in progress.

Installation

Installing RaZ on Linux can be made from the RaZ build directory by executing either the command cmake --build . --target install.

By default, the install location is /usr/local, which is a standard place for user builds. This needs superuser rights (sudo cmake --build . --target install). If you don't have those, feel free to change the install location by modifying the CMAKE_INSTALL_PREFIX variable.

If for some reason you want to manually install RaZ without using the command above, you can execute the following ones from the RaZ root directory:

sudo cp -r include/RaZ /usr/local/include
sudo cp build/libRaZ.a /usr/local/lib

After doing this, you can include RaZ and link it with -lRaZ to use it in your project!