HACKING.md

Hacking

Here is some wisdom to help you build and test this project as a developer and potential contributor.

If you plan to contribute, please read the CONTRIBUTING guide.

Developer mode

Build system targets that are only useful for developers of this project are hidden if the DEVELOPER_MODE option is disabled. Enabling this option makes tests and other developer targets and options available. Not enabling this option means that you are a consumer of this project and thus you have no need for these targets and options.

Developer mode is always set to on in CI workflows.

Presets

This project makes use of [presets][1] to simplify the process of configuring the project. As a developer, you are recommended to always have the latest CMake version installed to make use of the latest Quality-of-Life additions.

You have a few options to pass DEVELOPER_MODE to the configure command, but this project prefers to use presets.

As a developer, you should create a CMakeUserPresets.json file at the root of the project:

{
  "version": 2,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 14,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "dev",
      "binaryDir": "${sourceDir}/build/dev",
      "inherits": ["dev-mode", "vcpkg", "ci-<os>"],
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "dev",
      "configurePreset": "dev",
      "configuration": "Debug"
    }
  ],
  "testPresets": [
    {
      "name": "dev",
      "configurePreset": "dev",
      "configuration": "Debug",
      "output": {
        "outputOnFailure": true
      }
    }
  ]
}

You should replace <os> in your newly created presets file with the name of the operating system you have, which may be win64, linux or darwin. You can see what these correspond to in the CMakePresets.json file.

CMakeUserPresets.json is also the perfect place in which you can put all sorts of things that you would otherwise want to pass to the configure command in the terminal.

Note Some editors are pretty greedy with how they open projects with presets. Some just pick a preset and start configuring without further input from the developer, which can be confusing. Make sure that your editor configures what and when you actually want it to, for example in CLion you have to make sure only the dev-dev preset has Enable profile ticked in File > Settings... > Build, Execution, Deployment > CMake and in Visual Studio you have to set the option Never run configure step automatically in Tools > Options > CMake prior to opening the project, after which you can manually configure using Project > Configure Cache.

Dependency manager

The above preset will make use of the vcpkg dependency manager. After installing it, make sure the VCPKG_ROOT environment variable is pointing at the directory where the vcpkg executable is or you can directly set CMAKE_TOOLCHAIN_FILE with an absolute path. On Windows, you might also want to inherit from the vcpkg-win64-static preset, which will make vcpkg install the dependencies as static libraries. This is only necessary if you don't want to setup PATH to run tests.

Configure, build and test

If you followed the above instructions, then you can configure, build and test the project respectively with the following commands from the project root on any operating system with any build system:

cmake --preset=dev
cmake --build --preset=dev
ctest --preset=dev

If you are using a compatible editor (e.g. VSCode) or IDE (e.g. VS), you will also be able to select the above created user presets for automatic integration.

Please note that both the build and test commands accept a -j flag to specify the number of jobs to use, which should ideally be specified to the number of threads your CPU has. You may also want to add that to your user preset using the jobs property, see the presets documentation for more details.