Skip to main content

Building CherryGrove

This tutorial will help you build CherryGrove on your own machine. This is also a very good starting point for developing CherryGrove.

CherryGrove is still in a very early stage of development. Please check CherryGrove's currently supported platforms before you move on.

Introduction​

CherryGrove currently only uses CMake as the build system. We use the following dependency management strategies:

  • For header-only libraries, we use Git submodules and CMake's target_include_directories to include them automatically.
  • For CMake compatible libraries, we use Git submodules and CMake's add_subdirectory command to import it.
  • For some libraries, we download the source code, commit them into our repository, and build them together with our code. Get more information at Local Libraries Documentation.
  • For the rest of the libraries, we use GitHub Actions to build them in advance and they need to be downloaded for CherryGrove to build.

Prerequisites​

Git​

Since CherryGrove uses Git submodules, it's recommended to clone the repository using Git, rather than downloading zip from GitHub webpage.

Download and install Git at https://git-scm.org.

Check if Git is installed using:

git --version

Build Toolchain​

Compiler​

Clang/LLVM-build is the default toolchain. It's recommended on all platforms for better dead code eliminating and unified modern C++ support.

Linker​

We use lld-link that comes with LLVM on Linux and macOS, and MSVC LINK.EXE on Windows because weird ABI incompatibility issues. If you found a way to make lld-link work on Windows, please let us know.

Standard Library​

Prebuilt dependencies assume linkage against the platform's default C++ Standard Library: Microsoft STL for Windows, libstdc++ for Linux, and libc++ for macOS.

Building CherryGrove using incorrect C++ Standard Library will result in an ABI conflict while linking. Please build the prebuilt dependencies manually if you really need another standard library.

Installing Build Tools​

  1. Download and open the Microsoft Visual Studio installer from https://visualstudio.microsoft.com.
  2. Check Desktop development with C++ workload.
  3. Switch to Individual Components tab, and check the following components for the Clang/LLVM toolchain:
    • C++ Clang Compiler for Windows (xx.x.x)
    • MSBuild Support for LLVM (clang-cl) Toolset
tip

If you need to cross compile (e.g. arm64 Windows on x64 Windows), you should also switch to Individual Components and check the MSVC component for the other architecture (e.g. MSVC v1xx - VS 20xx C++ ARM64/ARM64EC build tools (latest)).

CMake​

Download and install CMake at https://cmake.org.

Check if CMake is installed using:

cmake --version

Ninja​

CherryGrove uses Ninja as low level build system on all platforms by default because of its compatibility and versability. If you don't want to use Ninja, don't be worry. C++ toolchain is a wonderful place and many IDEs come with Ninja / can add Ninja as a workload such as Microsoft Visual Studio and CLion.

Download Ninja at https://github.com/ninja-build/ninja/releases, and put it somewhere. Then set up system PATH variable to include Ninja's directory.

Check if Ninja is installed using:

ninja --version

7-zip​

You will need 7z-compatible compression software to decompress downloaded prebuilt dependencies.

Download and install 7-zip at https://7-zip.org. Then, set up system PATH variable to include 7-zip's installation directory (e.g. C:\Program Files\7-Zip) if you want to use the prebuilt dependency fetching scripts.

If you're using Windows 11 22H2 or later versions of Windows and you don't want to use the fetch scripts, you don't need to install anything. Doubleclicking the downloaded .7z files and extracting using File Explorer should just work.

gperf​

CherryGrove uses gperf to generate perfect hash functions for some of the internal data structures.

Download and install gperf at https://ftp.gnu.org/pub/gnu/gperf/. Then set up system PATH variable to include gperf's installation directory.

Check if gperf is installed using:

gperf --version

Clone Repository​

Remember to use the --recursive argument. Cloning might take several minutes to complete because of the large submodule tree.

git clone --recursive https://github.com/cherryridge/cherrygrove.git

Grab Prebuilt Dependencies​

Currently we have five prebuilt dependencies that need to be downloaded separately from GitHub Action's release. All of the archives from these releases are compressed using 7-Zip. You can download them all from running this script in cherrygrove/libs folder:

cd libs
./fetch_prebuilt_libs.ps1

You will need 7z in your PATH for the scripts to work.

You will probably need to download both debug and release builds if you want to set up a development environment. If you only want to build CherryGrove and use it, only download release builds.

note

Tips about bgfx's shaderc​

  1. The bgfx dependency has a shader compiler (shaderc) in it, which will be invoked post-build. If you see some errors about execution permission, you might need to run chmod +x lib/bgfx/<debug|release>/bin/shaderc.
  2. On Windows arm64, shaderc.exe is actually an x64 build because of some weird incompatibility errors building it targetting arm64 Windows. It should work fine unless you're using an older version of arm64 Windows 10, which is really rare.

Links, in case you need to download these dependencies manually:

  1. bgfx: https://github.com/cherryridge/dep_bgfx/releases/latest
  2. SoLoud: https://github.com/cherryridge/dep_soloud/releases/latest
  3. V8: https://github.com/cherryridge/dep_v8/releases/latest
  4. Wasmtime: https://github.com/cherryridge/dep_wasmtime/releases/latest

If you're downloading them manually, upon decompressing, put all of the files and folders into libs/<dependency_name>/<debug|release>. You should see a .gitignore file inside each destination folder before putting files in, which stops Git from tracking these files. The inner structure of the destination folder should look like this:

├───📁 include/
│   ├───📁 <dependency_name>/ (optional)
│   │   └───...
│   ├───📁 <dependency_name2>/ (optional)
│   │   └───...
│   └───📄 (...).<h|hpp|hh> (optional)
├───📁 ... (optional)
├───📄 <library_name>.<lib|a>
├───📄 <library_name>.pdb (optional)
├───📄 <library_name2>.<lib|a> (optional)
└───📄 VERSION.txt

Platform-Specific Dependencies​

Linux and macOS​

For Linux and macOS, you need to have wine64 installed to compile DX11 shaders using shaderc. For Linux, you can install it from your distro's package manager, for example in Ubuntu:

sudo apt install wine64

Linux​

For Linux, there are some additional dependencies for SDL3 (which also covers SoLoud and bgfx's dependencies) you need to install. Check out https://wiki.libsdl.org/SDL3/README-linux#build-dependencies for more details. For Ubuntu, run:

sudo apt install build-essential pkg-config libasound2-dev libpulse-dev libaudio-dev libfribidi-dev libjack-dev libsndio-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxfixes-dev libxi-dev libxss-dev libxtst-dev libxkbcommon-dev libdrm-dev libgbm-dev libgl1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev libibus-1.0-dev libudev-dev libthai-dev libpipewire-0.3-dev libwayland-dev libdecor-0-dev liburing-dev

Build​

It's recommended to use CMake support for Visual Studio instead of generating .sln files. Open the cherrygrove folder in Visual Studio, and it will probably prompt you to install the CMake workload, or you can also install it manually from the Visual Studio Installer. After that, Visual Studio will automatically generate build files for you.

If you don't have Ninja installed, you might also need to set the CMake generator to "Visual Studio 17 2022" in CMakePresets.json or just delete the file. It's not that difficult to set up Ninja on Windows, please.

Ensure the configuration is correctly generated, then switch build target to CherryGrove.exe and choose Build > Build CherryGrove.exe.

Product Explanation​

For default CMake presets, the products are located in out/<os>-<architecture>-<mode>. CherryGrove is monolithic, i.e. all of the code is located in the CherryGrove executable.

Copying assets and CherryGrove executable to another place and they should just work.

note

For packing CherryGrove to ship to end user, visit the next document about packing.

Troubleshooting​

Downloading​

  1. It takes forever to clone CherryGrove

    • Unfortunately there is no way to fix this because CherryGrove simply uses a lot of Git submodules and they also have many submodules inside of them. Under a typical network environment, cloning CherryGrove would take 1~5mins.

  2. Server timeout/unexpected EOF/other network issues while cloning

    • Simply retry using a better network. It's recommended to remove any downloaded files before retrying.
    • Consider using a proxy for Git. Git in command prompt/bash won't automatically pick up system proxy, so you might need to configure it using: 
      git config --global http.proxy <proxy_host>
      git config --global https.proxy <proxy_host>
    • If you're still not able to clone CherryGrove using command line, you are in really bad luck: You need to manually download code from GitHub.com webpage recursively for every Git submodule dependencies, as well as the dependencies of these dependencies. You are a legend if you managed to do so.

Building​

  1. CMake failed to generate project files

Testing​

  1. CherryGrove won't start

    warning

    It's a known bug that CherryGrove won't start under a directory path that has non-ASCII characters.

    • Try to locate and inspect log files like CherryGrove-<timestamp>.log in logs folder near the executable. If you believe that a bug had occured, consider reporting to us.
    • You can also try to debug using your IDE.

  2. The GUI is in a bad shape / is flickering / is wrongly scaled / won't respond to resizing

    • CherryGrove is still in a very early stage of development. For now (2025.11), that's pretty normal. At least you saw something happening :).