CMake Building¶
Once you have configured your project, you can run a CMake build. Most work with CMake Tools will be done with configuring, and the build process is much simpler.
Starting a build can be done in one of three ways:
Executing the CMake: Build command
Hitting the associated hotkey (the default being F7).
Pressing the Build button in the status bar.
When the build starts, the CMake Tools output panel will be opened and the output from the build tool will be shown as it runs. The Build button will change to a Stop button and may show a progress bar for the running build. Pressing the Stop button will cancel the running build. Attempting to execute a build while a build is running will cancel the running build and start a new one.
Note
The progress bar will only be shown if the build tool emits output lines that can be parsed to contain a percentage of the build progress. This includes Ninja and Makefile generators. MSBuild does not emit this information, so no progress bar will be visible.
The results of the build will be written to the directory specified by cmake.buildDirectory. This defaults to a subdirectory of the project directory, so the build results will be visible within the project explorer. The exact file paths will depend on the CMake project configuration.
The Default Target¶
CMake Tools persists a “default target” for the build process. The default
target is the “all” target (named ALL_BUILD in some generators), which will
build all targets CMake has designated for a default build.
The name of the default target is shown in the status bar to the right of the Build button in square brackets:
Clicking this button will show a quick-pick for all the target CMake Tools is aware of that can be built, along with the full path to the build result that will be generated by the target:
Building a Single Target¶
Instead of changing the build target, one can also request to build a single target a single time. Run the CMake: Build a target command, or hit the associated hotkey (defaults to Shift+F7).
Note
CMake will build dependent targets, even if they aren’t directly selected.
How CMake Tools Builds¶
Build Flags¶
CMake Tools builds by passing the --build flag to CMake. This flag is used
as a generator-agnostic build invocation tool. CMake tools also passes
--config <build-type> based on the current build type from the active
variant. This instructs multi-conf build tools on what
configuration they should build.
Additional flags to --build can be set with cmake.buildArgs,
and additional flags for the underlying build tool can be set with
cmake.buildToolArgs. These are advanced options and should only be
used if you know what you are doing.
The Build Environment¶
Environment variables will be inherited from the calling Visual Studio Code process, with additional variables from the cmake.buildEnvironment and cmake.environment setting.
If using a Visual Studio Kit, CMake Tools runs the build with the appropriate environment variables set to build with the chosen Visual Studio, much like how it sets these environment variables when configuring.
Cleaning Up¶
CMake Tools lets you clean the build output by running the CMake: Clean command. One can also run the CMake: Clean rebuild to quickly delete build results and run the build from scratch.
