Skip to content

Latest commit

 

History

History
104 lines (86 loc) · 11.2 KB

cmake-settings.md

File metadata and controls

104 lines (86 loc) · 11.2 KB
Raw

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.debugConfig The debug configuration to use when debugging a target null (no values) 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