A kit encompasses project-agnostic and configuration-agnostic informationabout how to build code. A kit can include:

• Make Raining Images In Visual Studio Code

• A set of compilers for some set of languages - These are locked at specificversions such that you can switch your compiler version quickly and easily.

• A Visual Studio installation - Building for VS is more complicated thansimply finding the necessary compiler executable. Visual C++ requires certainenvironment variables to be set to tell it how to find and link to theVisual C++ toolchain headers and libraries.

• A toolchain file - This is the lowest-level way to instruct CMake how tocompile and link for a target. CMake Tools handles toolchain files usingkits.

Using CMake to build #. OK, so now I knew how to build Visual Studio projects from command line. We had a pretty big C code base, that we wanted to build on Linux, macOS and Windows. Configure and build with CMake Presets in VS Code. CMake supports two files, CMakePresets.json and CMakeUserPresets.json, that allow users to specify common configure, build, and test options and share them with others.CMakePresets.json integration is available in cmake-tools version 1.7 and later. CMakePresets.json and CMakeUserPresets.json can be used to drive CMake in Visual Studio. In Visual Studio 2019 and later, you can add configurations and customize their settings by using the CMake settings editor. The editor is intended to be a simpler alternative to manually editing the CMakeSettings.json file, but if you prefer to edit the file directly, you can click the Edit JSON link in the upper right of the editor.

Kits are mostly CMake-generator-agnostic, although Visual Studio kits will havea “preferred” generator that will be used as a fallback to ensure a matchingMSBuild and .sln generator is used for the Visual C++ compiler.

Note

If you use Ninja there is no need to worryabout Visual Studio CMake Generators. CMake Tools will prefer Ninja if it ispresent unless configured otherwise.

Note

If you change the active Kit while a project is configured, the projectconfiguration will be re-generated with the chosen kit.

Note

Using a kit is recommended but optional. Opting-out of using kits willcause CMake to perform its own automatic detection.

How Are Kits Found and Defined?¶

Upon first startup, CMake Tools will scan the system foravailable toolchains. It looks in certain directories for the presence ofcompilers or Visual Studio installations (using vswhere) to populate theinitial list of Kits.

User-Local Kits¶

User-local kits are kits that are available to a particular user for allprojects open with CMake Tools.

The user-local list of kits is stored in a user-owned file, which you can editby invoking Edit CMake Kits from the command palette. It will open thecmake-kits.json file:

This file can be manually modified to define new global kits, and the contentsof this file will also be automatically controlled by CMake Tools via theautomated kit scanning.

Warning

Don’t modify any of the kits that CMake Tools defines itself: It willoverwrite any modifications during kit scanning. Seebelow for more information.

Project Kits¶

The default user-local kits are available for all projects using CMake Toolsfor a user. In addition, one can define project-local kits by creating a.vscode/cmake-kits.json file in the project directory. The contents of thisfile must be managed manually, but CMake Tools will automatically reload andrefresh when it sees this file added, removed, or changed. When changing kits,both user-local and project-local kits will be available for selection.

An example usage of project-local kits is if the project defines its ownCMake toolchain file(s). A toolchain kit can be definedthat specifies this file to be loaded. The .vscode/cmake-kits.json file canbe committed to source control and shared with other developers for easiercollaboration on the named toolchain.

Scanning Process¶

User-Local Kits can be updated by running Scan for Kits in thecommand palette. The following process occurs to find available kits:

1. Search the current PATH for compilers

   CMake tools will use the PATH environment variable for a list ofdirectories where compilers can be found.

   CMake Tools looks for gcc and clang binaries and asks eachexecutable for version information.

   For gcc, if a corresponding g++ executable resides in the samedirectory it is added to the kit as the corresponding C++ compiler. Thesame applies for a clang++ binary in the directory of a clangexecutable.

   Note

   At the moment, CMake Tools will automatically detect Clang andGCC only. If you’d like auto-detection for more tools,please open an issue on the GitHub page with information about thecompiler binary names and how to parse its version information.

2. Ask VSWhere about Visual Studio installations

   CMake tools includes a bundled vswhere.exe which it uses to ask aboutexisting Visual Studio instances installed on the system.

   For each of x86, amd64, x86_amd64, x86_arm, x86_arm64,amd64_x86, amd64_arm, and amd64_arm64, CMake Tools will check// for installed Visual C++ environments.// A kit is generated for each existing MSVC toolchain.

3. Save results to the user-local kits file

   When finished, the user-localcmake-kits.jsonfile will be updated with the new kit information.

   Warning

   The name of each kit is generated from the kit compilerand version information, and kits with the same name will beoverwritten in the file.

   To prevent custom kits from being overwritten, give them unique names.CMake Tools will not delete entries from cmake-kits.json, only addand update existing ones.

Kit Options¶

CMake defines several different options that can be specified on each kit intheir definition in cmake-kits.json, and these options can bemixed-and-matched as needed. For example, A single kit may request aVisual Studio environment while specifying clang-cl as a compiler.

See also

• How CMake Tools Configures - Explains how kits are applied during configuration

Compilers¶

Specifying language compilers is as simple as listing the paths to compilersfor CMake languages.

The most common CMake languages are C and CXX, and CMake Tools hasbuilt-in support for finding these, but any language can be specified:

Toolchain¶

CMake Tools will not automatically detect them, but you can also specify aCMake toolchain file in a kit:

CMake Tools will pass this path for CMAKE_TOOLCHAIN_FILE during configure.

Visual Studio¶

CMake Tools will automatically setup the environment for working with Visual C++when you use a Visual Studio code. It is advised to let CMake Toolsgenerate the kits first, then duplicate them and modify them.

The visualStudio key corresponds to a name of a Visual Studio installationobtained from VSWhere. The visualStudioArchitecture key corresponds to aVisual Studio target architecture that would be passed to the vcvarsall.batfile when entering the VS dev environment.

Note

To use Visual C++, both of visualStudio andvisualStudioArchitecturemust be specified. Omitting one will notwork.

Generic Options¶

In addition to the above options, the following may be specified:

preferredGenerator

The CMake generator that should be used with this kit if not the default.CMake Tools will still search in cmake.preferredGenerators fromsettings.json, but will fall back to this option if no generatorfrom the user settings is available

cmakeSettings

A JSON object that will be passed as a list of cache settings when runningCMake configure. Don’t use this for project-specific settings and options:Prefer to use the settings.json for that purpose.

This setting is most useful when the toolchain file respects additionaloptions that can be passed as cache variables.

environmentVariables

Make Raining Images In Visual Studio Code

A JSON object of key-value pairs specifying additional environmentvariables to be defined when using this kit.