Skip to content

Latest commit

 

History

History
55 lines (30 loc) · 3.92 KB

build.md

File metadata and controls

55 lines (30 loc) · 3.92 KB

Build with CMake Tools

Once you have configured your project, you can run a CMake build. Most of your time with CMake Tools will be spent configuring the build. The build process is much simpler.

You can start a build by:

  1. Running CMake: Build from the VS Code command pallette.
  2. Pressing the keyboard shortcut (the default is F7).
  3. Selecting the Build button in the VS Code status bar.

When the build starts, the CMake Tools output panel opens to display build tool output. The Build button will change to a Stop button, and may show a progress bar for the running build. Pressing the Stop button cancels the running build. Starting a build while another build is running will cancel the current build and start a new one.

Note: The progress bar only displays if the build tool emits output lines that can be parsed to get 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 are written to the directory specified by cmake.buildDirectory. This defaults to a subdirectory of the project directory, so the build results are visible within the project explorer. The exact file paths will depend on your CMake project configuration.

Build 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 builds all of the targets that 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:

Default target as shown in the status bar

Selecting this button shows a quick pick list for all the targets 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:

List of targets

Build a single target

You can build a single target without changing the current build target from the VS Code command pallette by running the CMake: Build a target command, or by pressing the keyboard shortcut (default is Shift+F7). CMake will build any 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-configuration build tools which configuration they should build.

For advanced scenarios, additional flags to --build can be set with cmake.buildArgs, and additional flags for the underlying build tool can be set with cmake.buildToolArgs.

The build environment

Environment variables are inherited from the calling Visual Studio Code process, with additional variables from the cmake.buildEnvironment and cmake.environment settings.

If you are using a Visual Studio Kit, CMake Tools runs the build with the appropriate environment variables set to build with the chosen version of Visual Studio, much like how it sets these environment variables during the CMakeTools configure step.

Clean build

To clean the build, from the VS Code command pallette run the CMake: Clean command. Or run the CMake: Clean rebuild command to quickly delete any build results and run the build from scratch.

Next steps