Navigate the Project Files: Configuration Files and Presets

Let's learn about the configuration files and presets of a typical CMake project.

We'll cover the following

The config-files for packages

A big part of the CMake ecosystem includes the external packages that projects can depend on. They allow developers to use libraries and tools in a seamless, cross-platform way. Packages that support CMake should provide a configuration file so that CMake understands how to use them.

Here are a few interesting details to bear in mind:

  • Config-files (original spelling) contain information regarding how to use the library binaries, headers, and helper tools. Sometimes, they expose CMake macros to use in our project.

  • Use the find_package() command to include packages.

  • CMake files describing packages are named <PackageName>-config.cmake and <PackageName>Config.cmake.

  • When using packages, we can specify which version of the package we need. CMake will check this in the associated <Config>Version.cmake file.

  • Config-files are provided by package vendors supporting the CMake ecosystem. If a vendor doesn't provide such a config-file, it can be replaced with a find-module (original spelling).

  • CMake provides a package registry to store packages system-wide and for each user.

The cmake_install.cmake, CTestTestfile.cmake, and CPackConfig.cmake files

These files are generated in the build tree by the cmake executable in the generation stage. As such, they shouldn't be edited manually. CMake uses them as a configuration for the cmake install action, CTest, and CPack. If we're implementing an in-source build (not recommended), it's probably a good idea to add them to the VCS ignore file.

CMakePresets.json and CMakeUserPresets.json

The configuration of the projects can become a relatively busy task when we need to be specific about things such as cache variables, chosen generators, the path of the build tree, and more—especially when we have more than one way of building our project. This is where the presets come in.

Users can choose presets through the GUI or use the command line to --list-presets and select a preset for the buildsystem with the --preset=<preset> option.

Presets are stored in the same JSON format in two files:

  • CMakePresets.json: This is meant for project authors to provide official presets.

  • CMakeUserPresets.json: This is dedicated to users who want to customize the project configuration to their liking (we can add it to our VCS ignore file).

Presets are project files, so their explanation belongs here. However, they are not required in projects, and they only become useful when we have completed the initial setup. So, feel free to skip to the next section and return here later, if needed:

Get hands-on with 1200+ tech skills courses.