CMake Build System Options

Contents

1. Using Presets
2. Customizing Presets

Using Presets

The CMake build system provided by the plugin template has only a few configuration options out of the box. Developers are of course free to add their own options (or even remove existing ones) to fit their needs.

Some of these options are set in the CMakePresets.json presets file using a simple inheritance scheme:

• A hidden "template" preset contains CMake configuration variables used by all platforms
• Platform-specific presets inherit from the template and add necessary configuration variables for their platform
• CI presets for each platform inherit from the platform-specific presets and set configuration variables to be used by CI (e.g. GitHub Actions) only

Warning

By default the CI presets will enable compilers to report warnings as errors just like on the obs-studio repository. The OBS project suggests using a "zero warnings" development style in which warnings are either fixed or analyzed, and then identified as unfortunate but also unavoidable before disabling the specific warning for the translation unit.

CMake GUI (Windows)

Available presets are displayed in the CMake GUI on Windows in the "Preset" selection box, with unavailable presets (due to not fulfilling specific requirements defined in the preset file) shown as disabled selection items. Selecting a preset will set up the configuration values defined in it:

CMake CLI (macOS, Ubuntu)

When using the command-line interface (CLI), available presets can be reported and selected using the appropriate commands at the project root:

# Show available presets for current platform
cmake --list-presets
# Select a preset
cmake --preset windows-x64

Customizing Presets

There are two options to customize a preset: Either create a CMakeUserPresets.json file with your own presets (which can be standalone or extend the presets defined in CMakePresets.json, or provide CMake cache variables directly.

Adding cache variables directly is no different to providing variables for a project that does not use presets. Variables can be set up using CMake GUI or provided directly on the command-line:

cmake --preset windows-x64 -DSOME_VARIABLE:TYPE=SOME_VALUE

This applies to new variables as well as variables set up in the preset, so the variable ENABLE_FRONTEND_API (which is disabled by default) can be changed directly in the GUI or by providing an alternative value in the command invocation:

cmake --preset windows-x64 -DENABLE_FRONTEND_API:BOOL=ON

Important

If the plugin is supposed to be interacting with the front-end via its API, it is correct to change the CMakePresets.json file to enable its use by default. Developers should not feel forced to keep the preset file as-is, but are encouraged to change it to meet their needs.

Quirks of CMake-GUI on Windows

While using the GUI on Windows might feel like the easiest way to interact with a CMake build configuration, it has some noticeable quirks and shortcomings:

• The GUI allows you to select a "custom" preset. When no configured project exists, its configuration will be empty. If a project was configured by selecting and configuring a preset before, switching to "custom" will make it inherit the current project configuration. Any changes you make in a "custom" preset will be overwritten by defaults if an actual preset is selected again.

Warning

It has been observed that CMake GUI will switch to a "custom" preset after generating a build system in some scenarios, but the exact reasons for this haven't been identified yet.

• The GUI does not expose the --fresh command line option that was added a while ago. This option tells CMake to use the current configuration options provided by the user, but throw away everything else and create a "fresh" project. This flag is forwarded to the obs-studio build project that is automatically generated on Windows and macOS (see also Build Dependency: libobs).

Note

While it is possible to delete the current cache from the "File" menu of CMake GUI, it seems to clear the files itself and does not call CMake to do the cleanup. Thus it does not provide the same functionality and convenience as the --fresh command line argument does.

Tip

For cross-platform development it's sometimes easier to use CMake via the command line and skip the GUI application entirely.