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.
| 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.Do not 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.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. |
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 passed onto CMake when configuring and to the compiler. |
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.mingwSearchDirs |
List of paths to search for a MinGW installation. This means that GCC does not need to be on your $PATH for it to be found via kit scanning. |
["C:\MinGW"] (Search in C:\MinGW for a MinGW installation) | no |
cmake.parallelJobs |
Specify the number of jobs run in parallel during the build. | 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 |
Directory where the root CMakeLists.txt is stored. |
${workspaceFolder} |
yes |
Some options 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. |
${workspaceRootFolderName} |
The name of the leaf directory in the workspace directory path. |
${buildType} |
The current CMake build type. For example: Debug, Release, MinSizeRel |
${buildKit} |
The current CMake kit name. For example: GCC 7.3.0 |
${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 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 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.
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.
- Learn about user vs. workspace settings
- Get started with CMake Tools on Linux
- Review How CMake Tools builds
- Explore the CMake Tools documentation