Tool-CMake-vscode-cmake-tools
microsoft/vscode-cmake-tools
https://github.com/microsoft/vscode-cmake-tools/blob/HEAD/docs/cmake-settings.md
Configure CMake Tools settings
CMake Tools supports a variety of settings that can be set at the user, or workspace, level via VSCode's settings.json file. This topic covers the available options and how they are used.
Options that support substitution, in the table below, allow variable references to appear in their strings. See variable substitution, below, for more information about variable expansion.
CMake settings
| Setting | Description | Default value | Supports substitution |
|---|---|---|---|
cmake.autoSelectActiveFolder |
If 'false', your active folder only changes if you manually run the CMake: Select Active Folder command. |
'true' | no |
cmake.buildArgs |
An array of additional arguments to pass to cmake --build. |
[] (empty array-no additional arguments) |
yes |
cmake.buildBeforeRun |
If true, build the launch/debug target before running the target. |
true |
no |
cmake.buildDirectory |
Specify the build directory (i.e. the root directory where CMakeCache.txt will be generated.) |
${workspaceFolder}/build |
yes |
cmake.buildEnvironment |
An object containing key:value pairs of environment variables, which will be passed only to the compiler. |
null (no environment variables specified) |
yes |
cmake.buildToolArgs |
An array of additional arguments to pass to the underlying build tool. | [] (empty array-no additional arguments) |
yes |
cmake.cacheInit |
Path, or list of paths, to cache-initialization files. Passed to CMake via the -C command-line argument. |
[] (empty array-no cache initializer files) |
no |
cmake.cmakePath |
Specify location of the cmake executable. | cmake (causes CMake Tools to search the PATH environment variable, as well as some hard-coded locations.) |
Supports substitution for workspaceRoot, workspaceFolder, workspaceRootFolderName, userHome, ${command:...} and ${env:...}. Other substitutions result in an empty string. |
cmake.cmakeCommunicationMode |
Specifies the protocol for communicating between the extension and CMake | automatic |
no |
cmake.configureArgs |
Arguments to CMake that will be passed during the configure process. Prefer to use cmake.configureSettings or CMake variants.It is not recommended to pass -D arguments using this setting. |
[] (empty array-no arguments) |
yes |
cmake.configureEnvironment |
An object containing key:value pairs of environment variables, which will be passed to CMake only when configuring. |
null (no environment variable pairs) |
yes |
cmake.configureOnEdit |
Automatically configure CMake project directories when the path in the cmake.sourceDirectory setting is updated or when CMakeLists.txt or *.cmake files are saved. |
true |
no |
cmake.configureOnOpen |
Automatically configure CMake project directories when they are opened. | null (prompt for configure) |
no |
cmake.configureSettings |
An object containing key:value pairs, which will be passed to CMake when configuring. The same as passing -DVAR_NAME=ON via cmake.configureArgs. NOTE: If you are setting an array argument within cmake.configureSettings, you should use array notation, i.e. "CONFIGURE_SETTINGS_LIST": [ "a", "b" ] |
null (no values) |
yes |
cmake.copyCompileCommands |
If not null, copies the compile_commands.json file generated by CMake to the path specified by this setting whenever CMake successfully configures. |
null (do not copy the file) |
yes |
cmake.defaultVariants |
Override the default set of variants that will be supplied when no variants file is present. See CMake variants. | no | |
cmake.environment |
An object containing key:value pairs of environment variables, which will be available when configuring, building, debugging, running or testing with CTest. |
null (no environment variables) |
yes |
cmake.generator |
Set to a string to override CMake Tools preferred generator logic. If set, CMake will unconditionally use it as the -G CMake generator command line argument. |
no | |
cmake.installPrefix |
If specified, sets a value for CMAKE_INSTALL_PREFIX when running CMake configure. If not set, no value will be passed.If CMAKE_INSTALL_PREFIX is set via cmake.configureArgs or cmake.configureSettings, cmake.installPrefix will be ignored. |
null (no value specified) |
yes |
cmake.loggingLevel |
A string setting that specifies how much output CMake Tools produces in its output channel. Set to one of "trace", "debug", "info", "note", "warning", "error", or "fatal". "trace" is the most verbose.Regardless of the logging level, CMake Tools writes all levels of logging to the CMake Tools log file. This file is useful if you need to troubleshoot CMake Tools |
"info" |
no |
cmake.skipConfigureIfCachePresent |
A boolean setting that allows users to skip the configure process if there is a CMake cache present | false |
no |
cmake.additionalCompilerSearchDirs |
List of paths to search for additional compilers, like a MinGW installation. This means that GCC does not need to be on your $PATH for it to be found via kit scanning. For example: ["C:\\MinGW\\bin"] (Search in C:\MinGW\bin for a MinGW installation) |
[] | no |
cmake.parallelJobs |
Specify the number of jobs run in parallel during the build. Using the value 1 will disable build parallelism. |
no | |
cmake.preferredGenerators |
A list of strings of generator names to try, in order, when configuring a CMake project for the first time. | no | |
cmake.saveBeforeBuild |
If true (the default), saves open text documents when build or configure is invoked before running CMake. |
true |
no |
cmake.sourceDirectory |
A directory or a list of directories where the root CMakeLists.txts are stored. |
${workspaceFolder} |
yes |
cmake.testEnvironment |
An object containing key:value pairs of environment variables, which will be available when debugging, running and testing with CTest. |
null (no environment variables) |
yes |
Variable substitution
Some settings support the replacement of special values in their string value by using a ${variable} syntax. The following built-in variables are expanded:
| Variable | Expansion |
|---|---|
${workspaceRoot} |
DEPRECATED. The full path to the workspace root directory. |
${workspaceFolder} |
The full path to the workspace root directory. |
${sourceDirectory} |
The full path to the root CMakeLists.txt. (not substituted for cmake.sourceDirectory, cmake.cmakePath, cmake.ctestPath, or in Kits) |
${workspaceRootFolderName} |
The name of the leaf directory in the workspace directory path. |
${buildType} |
The current CMake build type. For example: Debug, Release, MinSizeRel, RelWithDebInfo |
${buildKit} |
The current CMake kit full name. For example: GCC 7.3.0 |
${buildKitVendor} |
The current CMake kit vendor name. Possible values: GCC, MSVC, Clang and so on |
${buildKitTriple} |
The current CMake kit target triple. For example: arm-none-eabi |
${buildKitVersion} |
The current CMake kit version. For example: 9.3.0 |
${buildKitHostOs} |
The current CMake kit host OS. Possible values: win32, osx, linux and so on, all in lowercase |
${buildKitTargetOs} |
The current CMake kit target OS. Possible values: win32, osx, linux and so on, all in lowercase |
${buildKitTargetArch} |
The current CMake kit target architecture. Possible values: x86, x64, arm, aarch64 and so on, all in lowercase |
${buildKitVersionMajor} |
The current CMake kit major version. For example: 7 |
${buildKitVersionMinor} |
The current CMake kit minor version. For example: 3 |
${generator} |
The name of the CMake generator. For example: Ninja |
${projectName}|DEPRECATED. Expands to the constant string "ProjectName" CMake does not consider there to be just one project name to use. The concept of a single project does not work in CMake. Use ${workspaceRootFolderName}, instead. |
|
${userHome} |
The full path to the current user's home directory. |
Environment variables
Environment variables are expanded using the ${env:VARNAME} and ${env.VARNAME} syntax, where VARNAME is the environment to variable to expand. If the named environment variable is undefined, the expansion is an empty string.
Variant substitution
Variant options are expanded using the ${variant:VARIANTNAME} syntax, where the name of the currently active choice of the provided VARIANTNAME variant option is expanded. If the variant option is undefined, the expansion is an empty string.
Command substitution
CMake Tools can expand VS Code commands. For example, you can expand the path to the launch target by using the syntax ${command:cmake.launchTargetPath}
Be careful with long-running commands because it isn't specified when, or how many times, CMake Tools will execute a command for a given expansion.
Supported commands for substitution:
| command | substitution |
|---|---|
cmake.getLaunchTargetPath |
The full path to the target executable, including the filename. The existence of the target is not validated. |
cmake.getLaunchTargetDirectory |
The full path to the target executable's directory. The existence of the directory is not validated. |
cmake.getLaunchTargetFilename |
The name of the target executable file without any path information. The existence of the target is not validated. |
cmake.launchTargetPath |
The full path to the target executable, including the filename. If cmake.buildBeforeRun is true, invoking this substitution will also start a build. |
cmake.launchTargetDirectory |
The full path to the target executable's directory. If cmake.buildBeforeRun is true, invoking this substitution will also start a build. |
cmake.launchTargetFilename |
The name of the target executable file without any path information. If cmake.buildBeforeRun is true, invoking this substitution will also start a build. |
cmake.buildTargetName |
The current target selected for build. |
cmake.buildType |
Same as ${buildType}. The current CMake build type. |
cmake.buildKit |
Same as ${buildKit}. The current CMake kit name. |
cmake.buildDirectory |
The full path to the directory where CMake cache files are located. |
cmake.tasksBuildCommand |
The CMake command used to build your project based on the currently selected Kit + Variant + Target. Suitable for use within tasks.json. |
cmake.activeFolderName |
The name of the active folder (e.g. in a multi-root workspace) |
cmake.activeFolderPath |
The asolute path of the active folder (e.g. in a multi-root workspace) |
cmake.activeConfigurePresetName |
The name of the active configure preset. |
cmake.activeBuildPresetName |
The name of the active build preset. |
cmake.activeTestPresetName |
The name of the active test preset. |
Next steps
- Learn about user vs. workspace settings
- Get started with CMake Tools on Linux
- Review How CMake Tools builds
- Explore the CMake Tools documentation