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 uses the CMake build system only. 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. You also don't need to manage them on your own.
  • For libraries that are meant to be downloaded and compiled with the project, we commit them into our repository and build them together with other source files. Get more information at Local Libraries Documentation.
  • For other libraries, we use GitHub Actions to build them in advance, and you need to grab them from the corresponding repositories, or CherryGrove won't build successfully.

Prerequisites​

Build Toolchain​

warning

Prebuilt dependencies assume linkage against the platform's default C++ Standard Library:

  • Windows: MSVC, Microsoft STL
  • Linux: GCC, libstdc++
  • MacOS: Clang, libc++

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.

It's recommended to use Microsoft Visual Studio or Microsoft Visual Studio Code (VS Code) to build CherryGrove on Windows. And also, it's recommended to use the MSVC toolchain.

To get the toolchain, download the Microsoft Visual Studio installer from https://visualstudio.microsoft.com.

Check Desktop development with C++ in Desktop & Mobile section workload upon installing.

If you need to target a different architecture (e.g. targetting arm64 Windows on x64 Windows), you should 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)).

  • If you prefer VS Code:

    Download and install VS Code from https://code.visualstudio.com.

    Install C/C++ Extension from Extensions Marketplace.

    Install CMake Tools Extension from Extensions Marketplace.

    If you don't want to manually type in commands for building and debugging, configure the extension so it shows buttons in the status bar:

    "cmake.options.statusBarVisibility": "icon"

    (Optional) Install CMake Extension from Extensions Marketplace for better CMake intellisense.

    (Optional) Install C/C++ Themes Extension for better C++ syntax highlighting.

    (Optional) Install clangd Extension for better C++ language features in further development.

    You also need to install clangd binary on your system. Download it from https://github.com/clangd/clangd/releases, or just use the automatic installation prompt from the extension, because the extension sometimes won't work with the latest clangd and you need to find the latest compatible one in O(n) yourself.

    After installing clangd manually, set up system PATH variable to include clangd's installation directory, and configure VS Code to disable C/C++ Extension's IntelliSense engine to avoid conflicts:

    "C_Cpp.intelliSenseEngine": "disabled"

    Clangd needs compile_commands.json to provide accurate language features. You can generate it using the CMake Tools Extension by adding this to your settings.json:

    "cmake.copyCompileCommands": "${workspaceFolder}/compile_commands.json",
    "clangd.arguments": [
        //(Optional) Always index files even you don't open them
        "--background-index",
        //Point to `compile_commands.json` in the root directory
        "--compile-commands-dir=${workspaceFolder}"
    ]

    After setting up, send a Cmake: Configure command to generate compile_commands.json, and restart VS Code. Clangd should be working to generate caches now.

  • If you're using Microsoft Visual Studio (you're probably not preferring it):

    Go through the MSVC toolchain installation process and launch Visual Studio, then open the cherrygrove folder using Open a local folder, or click Open with Visual Studio in File Explorer.

    Visual Studio should automatically detect CMakeLists.txt and CMakePresets.json, and start generating the f**king linux-arm64-debug configuration for you. Stop it by switching to another configuration like windows-x64-debug, but don't switch too fast or it will somehow break the process and fail to generate. Good luck.

CMake​

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

Check if CMake is installed using:

cmake --version

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

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.

Install ninja according to your OS:

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

NASM​

CherryGrove uses SDL_image dependency to support AVIF texture input format, which involves compiling x86 assembly, so we need a x86 assembly compiler on x86 builds. NASM is recommended: https://nasm.us.

Get NASM at https://nasm.us/pub/nasm/releasebuilds/?C=M;O=D: click on the latest version (the top one without rc), go into win64 and download the nasm-<version>-installer-x64.exe installer. Run the installer and follow the instructions.

Check if NASM is installed using:

nasm -v

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.

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 Depedencies​

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>/shaderc.
  2. On Windows arm64, shader compiler (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. LuaJIT: https://github.com/cherryridge/dep_luajit/releases/latest
  4. V8: https://github.com/cherryridge/dep_v8/releases/latest
  5. Wasmtime: https://github.com/cherryridge/dep_wasmtime/releases/latest

Upon decompressing, the files inside should look like this:

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

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.

Additional Dependencies for Linux​

For Linux, there are some additional dependencies you also need to install. In Ubuntu, run this command to install them:

sudo apt install pkg-config libx11-dev libwayland-dev wayland-protocols libxkbcommon-dev libxkbcommon-x11-dev libxrandr-dev libxinerama-dev libgl1-mesa-dev x11proto-core-dev libxcursor-dev libxi-dev libgl-dev libasound2-dev libjack-jackd2-dev liblz4-dev libzstd-dev

Build​

You can deduce your build system by the software you're using, or by the build system files generated inside of out directory. If you're using an IDE, it may put subfolders of <os>-<architecture>-<mode> inside out directory instead of putting everything directly in out, and so does the commands and the products.

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. everything is in the CherryGrove executable, but except for:

  1. Shaders in shaders folder.
  2. Assets in assets folder.

Copying assets, shaders 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 :).