The Power of CMake Presets

CMake 3.19 was officially released a couple of months ago, and one of the biggest – and most exciting – new features is the addition of presets. What are presets, you might ask, and why should we be excited about them?

Presets are a bunch of pre-set CMake options that enable developers to ensure that multiple configurations remain consistent, even when using different compiler tool chains, inserting different debugger or profiler options, or building selected packages within a project. Essentially, you put definitions of the CMake options you want into one of two JSON files: one associated with the project, and one for the user.

While this sounds like a bit of a trivial feature, it’s becoming more and more common to see several arguments needing to be passed to CMake to configure different combinations. A preset combination then simplifies and makes builds less error-prone while opening up several really powerful use cases.

• Self-documentation. With consistent naming conventions, you can make it very easy to build all the variants of a project your team needs – without documentation and without lookup. No more scanning READ.MEs or the project Wiki to find just the right set of defines for a platform, product, language, or localization.
• CI communication. The CI team doesn’t need to know as many details about your application, especially if you have a custom build you need. You just ask them for a builder for a new preset. They don’t have to get the specifics from you – you just add them to your preset files.
• Decoupled development. Because the presets can be personalized by each developer, you can change build options without needing to make changes to the official repo or having the CI team update their configs. That makes it much easier to decouple individual developer workflows from the build logic.
• Scripts. Collapsing down five or six -DOPTION_FOO into a single preset makes it much easier to create meaningful (and readable) scripts.
• IDEs. Even more tedious than specifying all options on the command line is specifying them in IDE dialogs, which is something that often can’t be automated. Presets use an IDE- friendly format (JSON), which is meant to be easily consumed by IDEs and tool makers. The VSCode CMake extension is adding support for it and we can expect that Qt Creator won’t be far behind. But at least when using Qt Creator, you can already import an existing build directory, reusing its presets.

We’ve been using presets for our kddockwidgets project very successfully – look there for an example of a CMake preset file in action.

For more information about KDDockWidgets and to see a demo, visit our KDDockWidgets webpage.

Kevin Funk's whitepaper on CMake for Qt might be of interest to you as well, especially if you're still only considering moving to Qt 6.