CMake Configuring

CMake Tools wraps the CMakeconfigure process separately from thebuildprocess.

A Crash-Course on CMake’s Configuration Process

For those new to CMake,Configure refers to the process of detectingrequirements and generating the build files that will produce the finalcompiled artifacts.

To understand how CMake Tools interacts with CMake’s configure process, a fewthings must be discussed:

  • TheCMake Cache is a list of key-value pairs that persist betweenexecutions of the configure process. It contains a few different types ofvalues:

    • Values that are often heavy or slow to compute, such as whether a-flagor#include file is supported by the compiler.

    • Values that rarely change, such as the path to a header/library.

    • Values that offer control to the developer, such asBUILD_TESTINGto determine whether or not to build test libraries/executables.

  • Cache initializer arguments are the arguments passed to CMake that setvalues in the cache before any CMake scripts are executed. This lets onecontrol build settings. On the CMake command line, these appear as-Darguments1.

  • Unless overwritten or deleted, values in the CMake Cache will persist betweenexecutions of CMake.

  • The result of aconfigure depends on the CMakeGenerator. TheGeneratortells CMake what kind of tool will be used to compile and generate the resultsof the build, since CMake doesn’t do the build itself. There are severalfamilies of generators available:

    • Ninja - Emits files for theNinja build tool.This is the generator CMake Tools will always try first, unless configuredotherwise. (Seecmake.preferredGenerators).

    • Makefile - Emits aMakefile for the project that can be built viamake.

    • Visual Studio - Emits visual studio solutions and project files. There aremany different Visual Studio generators, so it is recommended to let CMakeTools automatically determine the appropriate generator.

    Regardless of generator, CMake Tools will always support building from withinVisual Studio Code. Choosing a particular generator is unimportant2.

1

CMake also supports a-C argument, but this isn’t used by orconfigurable from CMake Tools.

2

But you should useNinja.

How CMake Tools Configures

CMake Tools speaks to CMake overCMake Server, an execution mode of CMakewherein a persistent connection is held open to query information and getproject information.

When CMake Tools runs the configure step, it takes a few things intoconsideration to run the configuration:

  1. The active kit -CMake Tools’ Kits tell CMake Tools about thetoolchains available on your system that can be used with CMake to buildyour projects.

    • ForToolchain, CMake Tools sets the CMake cache variableCMAKE_TOOLCHAIN_FILE to the path to the file specified by the kit.

    • ForCompilers, CMake Tools sets theCMAKE_<LANG>_COMPILERcache variable to point to the path for each<LANG> defined in thekit.

    • ForVisual Studio, CMake Tools starts the CMake Server process with theenvironment variables necessary to use the selected Visual Studioinstallation. It also setsCC andCXX tocl.exe to forceCMake to detect the Visual C++ compiler as the primary compiler, even ifother compilers like GCC are present on the$PATH.

    Each kit may also define additional cache variable settings requires for thekit to operate. A kit may also define apreferredGenerator.

    See also

  2. The generator to use - CMake Tools tries not to let CMake decide implicitlyon which generator to use. Instead it tries to detect a “preferred” generatorfrom a variety of sources, stopping when it finds a valid generator:

    1. The config settingcmake.generator.

    2. The config settingcmake.preferredGenerators - Each elementin this list is checked for validity, and if one matches, it is chosen.The list has a reasonable default that will work for most environments.

    3. The kit’spreferredGeneratorattribute. Automatically generated Visual Studio kits will set thisattribute to the Visual Studio generator matching their version.

    4. If no generator is found, CMake Tools produces an error.

  3. The configuration options - CMake Tools has a variety of locations whereconfiguration options can be defined. They are searched in order and mergedtogether, with later searches taking precedence in case of overlapping keys:

    1. Thecmake.configureSettings option fromsettings.json.

    2. Thesettings value from the activeVariant Options.

    3. BUILD_SHARED_LIBS is set based onVariant Options.

    4. CMAKE_BUILD_TYPE is set based onVariant Options.

    5. CMAKE_INSTALL_PREFIX is set based oncmake.installPrefix.

    6. CMAKE_TOOLCHAIN_FILE is set forToolchain.

    7. ThecmakeSettings attribute on theactive kit.

    Additionally,cmake.configureArgs are passedbefore any ofthe above.

  4. The configure environment - CMake Tools sets environment variables for thechild process it runs for CMake. Like the configuration options, values aremerged from different sources, with later sources taking precedence:

    1. The environment variables required by the activekit.

    2. The value ofcmake.environment.

    3. The value ofcmake.configureEnvironment.

    4. The environment variables required by the activevariant.

All of the above are taken into account to perform the configure. Once finished,CMake Tools will load project information from CMake and generate diagnosticsbased on CMake’s output.You are now ready to build!

Configuring Outside of CMake Tools

CMake Tools is built to play nicely with an external CMake process. If youchoose to run CMake from another command line or other IDE/tool, all shouldwork successfully (provided the host environment is set up properly).

Nevertheless, be aware: CMake Tools will be unaware of any changes made by anexternal CMake process, and you will need to re-run the CMake configure withinCMake Tools to have up-to-date project information.

A “Clean” Configure

CMake Tools also has the concept of a “clean configure,” executed by runningCMake: Delete cached built settings and reconfigure. The process consistssimply of deleting theCMakeCache.txt file andCMakeFiles directoryfrom the build directory. This is enough to reset all of CMake’s default state.Should additional cleaning be necessary, it must be done by hand.

This process is required for certain build system changes, but may be convenientas a “reset” if you have tweaked any configuration settings outside of CMakeTools.

CMake Tools will also do thisautomatically if you change the activekit. CMake can’t yet properly handle changing the toolchainwithout deleting the configuration data.