Building the project

Guide how to build Jazz² Resurrection.

The project requires following tools and libraries to build it successfully:

  • CMake 3.15 or newer
  • C++ compiler with C++17 support — any newer version of GCC, Clang and MSVC should work, MinGW and Clang-CL toolchains should be also supported
  • OpenGL 3.0, OpenGL|ES 3.0 or WebGL 2.0 library (alternatively ANGLE or Mesa translation library)
  • GLEW (required only on Windows)
  • GLFW or SDL2 (not required on Android and UWP, because these platforms use a custom backend)
  • zlib

In addition, these libraries are required for an optimal experience:

  • OpenAL — audio support
  • libopenmpt — module music playback
  • libogg / libvorbis — .ogg file support (not needed for original levels)
  • libwebp — .webp file support (not needed for original levels)
  • AngelScript — AngelScript scripting support
  • liblua — Lua scripting support (currently not supported)

It tries to download or compile all libraries automatically, but in case of build errors a manual download is necessary. Also, system-wide libraries have priority over the bundled ones, so in case of any incompatibility just install the system libraries.

How to get started

Clone the repository using any Git client, IDE, or command line:

git clone https://github.com/deathkiller/jazz2-native.git

To configure CMake, following commands can be used:

mkdir build
cmake -B build -D CMAKE_BUILD_TYPE=Debug

Alternatively, change CMAKE_BUILD_TYPE to Release to enable all performance optimizations and disable debugging. You can also specify build configuration parameters, which are described below. To start actual build of the project, use following commands:

make -j $(nproc) -C build

Everything should be built in the "build" directory. Additionally, you can create a symbolic link to "Content" directory or copy it to "build" directory manually:

ln -s "$(pwd)/Content" "$(pwd)/build/Content"

Building on Android

Android build requires Android SDK and NDK installed, see Get started with the NDK. Assembling APK files also requires Gradle. Path to Gradle can be supplied by GRADLE_HOME environment variable if not detected automatically. The build can be configured using a similar command as above:

mkdir build
cmake -B build -D CMAKE_BUILD_TYPE=Debug \
    -D NCINE_BUILD_ANDROID=ON \
    -D NCINE_UNIVERSAL_APK=ON \
    -D NCINE_NDK_ARCHITECTURES="arm64-v8a;armeabi-v7a"

See Platform-specific parameters for Android for more details. Then following commands can be used to build the project and assemble the APK file:

make -j $(nproc) -C build
cd build
gradle assembleDebug

Alternatively, replace assembleDebug with assembleRelease to create release APK file.

Building on Windows

On Windows, Visual Studio can be used. Using already included .sln is not recommended, because it requires manual configuration. Instead the project can be opened as CMake directory directly in Visual Studio, or it can be configured using a similar command as above:

mkdir build
cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 ^
    -D CMAKE_SYSTEM_PROCESSOR=x64 ^
    -D NCINE_COPY_DEPENDENCIES=ON

See Platform-specific parameters for Windows for more details. To build it for 32-bit operating system, use Win32 instead of x64. To change version of VS toolset, use -D CMAKE_GENERATOR_TOOLSET=… parameter. By default CMake creates a new Visual Studio .sln solution and project files in "build" directory that can be opened easily afterwards. Building with Clang-CL compiler is also possible specifying -T ClangCL parameter.

Building for Xbox (Universal Windows Platform)

The same commands can be used as for Windows, but two additional parameters must be specified to change the target:

cmake -B build -D CMAKE_BUILD_TYPE=Debug -A x64 ^
    -D CMAKE_SYSTEM_PROCESSOR=x64 ^
    -D CMAKE_SYSTEM_NAME=WindowsStore ^
    -D CMAKE_SYSTEM_VERSION="10.0"

Additionaly, a code-signing certificate is required to create an installable .msixbundle package. See Platform-specific parameters for Universal Windows Platform for more details.

Build configuration parameters

By default it tries to find the first available backend for the currently installed libraries. GLFW is usually preferred over SDL2, because it's more lightweight. On the other hand, SDL2 usually has better gamepad support and better support in general. The following parameters can be used to customize the build:

  • CMAKE_BUILD_TYPE — Build configuration
    • Possible values: Debug, Release
  • CMAKE_INSTALL_PREFIX (default "/usr/local") — Install prefix on Unix systems
  • NCINE_DATA_DIR (default "./Content") — Path to "Content" game data directory
    • Some build targets include "Content" directory directly inside the executable package
  • NCINE_DOWNLOAD_DEPENDENCIES (default ON) — Download all missing dependencies automatically
  • NCINE_EMBED_SHADERS (default ON) — Embed shader files inside executable
  • NCINE_PREFERRED_BACKEND (default "GLFW") — Preferred backend on desktop
    • Possible values: GLFW, SDL2
    • Ignored on Android and UWP platforms
  • NCINE_VERSION_FROM_GIT (default ON) — Set current game version from Git repository automatically
  • NCINE_WITH_THREADS (default ON except on Emscripten) — Allow to use multiple threads for better performance
  • NCINE_WITH_OPENGLES (default OFF) — Use OpenGL|ES library instead of OpenGL
  • NCINE_WITH_ANGLE (default OFF except on UWP) — Enable Google ANGLE library support
  • NCINE_WITH_GLEW (default ON) — Use GLEW library
  • NCINE_WITH_BACKWARD (default ON) — Enable better exception handling
  • NCINE_WITH_WEBP (default OFF) — Enable .webp image file support, requires libwebp library
  • NCINE_WITH_AUDIO (default ON) — Enable audio support, requires OpenAL library
  • NCINE_WITH_VORBIS (default ON) – Enable .ogg audio file support, requires libvorbis library
  • NCINE_WITH_OPENMPT (default ON) – Enable module music audio file support, requires libopenmpt library
    • NCINE_COMPILE_OPENMPT (default OFF) – Download and compile libopenmpt from source automatically
  • NCINE_WITH_ANGELSCRIPT (default OFF) — Enable AngelScript scripting support
    • ANGELSCRIPT_VERSION_TAG allows to specify the version to be downloaded if NCINE_DOWNLOAD_DEPENDENCIES is enabled
  • NCINE_WITH_LUA deprecated — Enable Lua scripting support
  • NCINE_WITH_IMGUI (default OFF) — Enable integration with Dear ImGui library
    • IMGUI_VERSION_TAG allows to specify the version to be downloaded

Platform-specific parameters for Android

  • NCINE_BUILD_ANDROID (default OFF) — Enable building for Android platform
  • NCINE_ASSEMBLE_APK (default ON) — Assemble Android APK file, requires with Gradle
  • NCINE_NDK_ARCHITECTURES (default "arm64-v8a") — Semicolon-separated list of target CPU architectures
    • Possible values: arm64-v8a (for 64-bit ARM), armeabi-v7a (for 32-bit ARM), x86, x86_64
  • NCINE_UNIVERSAL_APK (default OFF) — Create universal APK containing all specified CPU architectures
  • NDK_DIR — Android NDK directory, usually detected automatically

Platform-specific parameters for Linux

  • NCINE_ASSEMBLE_DEB (default OFF) — Assemble DEB package of the game
  • NCINE_ASSEMBLE_RPM (default OFF) — Assemble RPM package of the game
  • NCINE_BUILD_FLATPAK (default OFF) — Build Flatpak version of the game
  • NCINE_LINUX_PACKAGE — Override Linux package name, otherwise "Jazz² Resurrection" will be used
  • NCINE_OVERRIDE_CONTENT_PATH — Override "Content" directory path
    • If not specified, following path will be used: CMAKE_INSTALL_PREFIX "/share/" NCINE_LINUX_PACKAGE "/Content/"
  • NCINE_PACKAGED_CONTENT_PATH (default OFF) — Use alternative path search strategy
    • If enabled, "Content" will be always relative to current directory
    • Has higher priority than NCINE_OVERRIDE_CONTENT_PATH

Platform-specific parameters for Windows

  • DEATH_WITH_VC_LTL (default ON) — Build with VC-LTL for lighter binaries, requires VC-LTL
  • NCINE_COPY_DEPENDENCIES (default OFF) — Copy all required libraries to build target directory automatically

Platform-specific parameters for Universal Windows Platform

  • NCINE_UWP_CERTIFICATE_THUMBPRINT — Code-signing certificate thumbprint
    • Use either NCINE_UWP_CERTIFICATE_THUMBPRINT or NCINE_UWP_CERTIFICATE_PATH
  • NCINE_UWP_CERTIFICATE_PATH (default "UwpCertificate.pfx") — Code-signing certificate path
  • NCINE_UWP_CERTIFICATE_PASSWORD (optional) — Code-signing certificate password for NCINE_UWP_CERTIFICATE_PATH

Advanced parameters

  • DEATH_CPU_USE_RUNTIME_DISPATCH (default ON if DEATH_CPU_USE_IFUNC) — Build with runtime dispatch for CPU-dependent functionality, see Death::Cpu
  • DEATH_CPU_USE_IFUNC (default ON if supported) — Allow using GNU IFUNC for runtime CPU dispatch
  • DEATH_RUNTIME_CAST (default ON) — Enable Death::runtime_cast() optimization
  • DEATH_TRACE (default ON) — Enable runtime event tracing, see Asserts.h
  • DEATH_TRACE_ASYNC (default ON if NCINE_WITH_THREADS) — Enable asynchronous processing of event tracing for better performance
  • NCINE_ADDRESS_SANITIZER (default OFF) — Enable AddressSanitizer memory error detector
  • NCINE_ARCH_EXTENSIONS — Target CPU architecture extensions (instruction sets)
    • Depends on target CPU and compiler support
    • See documentation of /arch (MSVC) and -m (GCC) for more details
  • NCINE_CODE_COVERAGE (default OFF) — Enable gcov instrumentation for testing code coverage
  • NCINE_GCC_HARDENING (default OFF) — Enable memory corruption mitigation methods of GCC
  • NCINE_LINKTIME_OPTIMIZATION (default ON) — Compile with link-time optimization
  • NCINE_UNDEFINED_SANITIZER (default OFF) — Enable UndefinedBehaviorSanitizer detector

Debugging parameters

  • NCINE_AUTOVECTORIZATION_REPORT (default OFF) — Enable report generation from compiler auto-vectorization
  • NCINE_INPUT_DEBUGGING (default OFF) — Enable extensive (gamepad) input debugging and logging
  • NCINE_PROFILING (default OFF) — Enable profiling
  • NCINE_STRIP_BINARIES (default OFF) — Strip debug symbols from binaries for smaller size
  • NCINE_WITH_FIXED_BATCH_SIZE (default OFF) — Enable fixed batch size for rendering
  • NCINE_WITH_RENDERDOC deprecated — Enable integration with RenderDoc
  • NCINE_WITH_TRACY (default OFF) — Enable integration with Tracy frame profiler
    • TRACY_VERSION_TAG allows to specify the version to be downloaded

Game-specific parameters

  • DISABLE_RESCALE_SHADERS (default OFF) — Disable rescale shaders and use only nearest neighbor
  • SHAREWARE_DEMO_ONLY (default OFF) — Shareware Demo only, usually used on Emscripten platform
  • WITH_MULTIPLAYER (default OFF) — Enable experimental multiplayer support