{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}
When your custom or preferred tools generate your cache, CMake places files under .cmake/api/v1/response that Visual Studio uses to populate the editor with information specific to your project structure.
Editing CMakeLists.txt files
To edit a CMakeLists.txt file, right-click on the file in Solution Explorer and choose Open. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about CMakeLists.txt, see the CMake documentation.
As soon as you save the file, the configuration step automatically runs again and displays information in the Output window. Errors and warnings are shown in the Error List or Output window. Double-click on an error in the Error List to navigate to the offending line in CMakeLists.txt.
Language services for CMake
Language services for CMake are available in Visual Studio 2019 version 16.5 or later. It supports code navigation features like Go To Definition, Peek Definition, and Find All References for CMake variables, functions, and targets in CMake script files. For more information, see Code Navigation for CMake Scripts.
CMake project manipulation
CMake project manipulation is available in Visual Studio 2019 version 16.5 or later. Project manipulation enables you to add, remove, and rename source files and targets in your CMake project without manually editing your CMake scripts. When you add or remove files from the Solution Explorer, Visual Studio automatically edits your CMake project. There could be more than one place where it makes sense to add or remove a reference to a CMake script. If so, Visual Studio asks you where you want to make the change and displays a preview of the proposed changes. For step-by-step instructions, see Add, Remove, and Rename Files and Targets in CMake Projects.
IntelliSense for CMake projects
By default, Visual Studio uses the IntelliSense mode that matches the compiler and target architecture specified by the active CMake configuration.
If CMakePresets.json is your active CMake configuration file, then you can specify IntelliSense options using intelliSenseMode and intelliSenseOptions in the Visual Studio Settings vendor map. For more information, see the Visual Studio Settings vendor map reference.
If CMakeSettings.json is your active CMake configuration file, then you can specify IntelliSense options using intelliSenseMode in CMakeSettings.json. For more information, see the CMakeSettings.json reference.
In Visual Studio 2019 version 16.9 and later, Visual Studio automatically configures IntelliSense in CMake projects based on CMake variables when you use a CMake toolchain file. For more information, see Configure IntelliSense with CMake Toolchain Files.
Vcpkg integration
CMake projects opened in Visual Studio integrate with vcpkg, a cross-platform C/C++ dependency manager. Before using vcpkg with Visual Studio, you must run vcpkg integrate install. For instructions and more information on vcpkg, see the vcpkg documentation.
If CMakeSettings.json is your active configuration file, Visual Studio automatically passes the vcpkg toolchain file (vcpkg.cmake) to CMake. This behavior is disabled automatically when you specify any other toolchain in your CMake Settings configuration.
If CMakePresets.json is your active configuration file, you'll need to set the path to vcpkg.cmake in CMakePresets.json. We recommend using the VCPKG_ROOT environment variable instead of an absolute path to keep the file shareable. For more information, see Enable vcpkg integration with CMake Presets. CMakePresets.json is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file.
Run CMake from the command line
If CMakePresets.json is your active CMake configuration file, then you can easily reproduce your local builds outside of Visual Studio. For more information, see Run CMake from the command line or a CI pipeline. CMakePresets.json is supported in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file.
If CMakeSettings.json is your active CMake configuration file, then you'll need to manually pass the arguments that are encoded in your CMakeSettings.json file to CMake. If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps:
Run the appropriate vsdevcmd.bat file (x86/x64). For more information, see Building on the command line .
Switch to your output folder.
Run CMake to build or configure your app.
Visual Studio 2017 has rich support for CMake, including cross-platform CMake projects. The Visual C++ Tools for CMake component uses the Open Folder feature to enable the IDE to consume CMake project files (such as CMakeLists.txt) directly for the purposes of IntelliSense and browsing. Both Ninja and Visual Studio generators are supported. If you use a Visual Studio generator, it generates a temporary project file and passes it to MSBuild. However, the project is never loaded for IntelliSense or browsing purposes. You also can import an existing CMake cache.
Installation
Visual C++ Tools for CMake is installed as part of the Desktop development with C++ and Linux Development with C++ workloads.
For more information, see Install the C++ Linux workload in Visual Studio.
IDE integration
When you choose File > Open > Folder to open a folder containing a CMakeLists.txt file, the following things happen:
Visual Studio adds a CMake menu item to the main menu, with commands for viewing and editing CMake scripts.
Solution Explorer displays the folder structure and files.
Visual Studio runs CMake and optionally generates the CMake cache for the default configuration, which is x86 Debug. The CMake command line is displayed in the Output Window, along with other output from CMake.
In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources.
You can open folders containing any number of CMake projects. Visual Studio detects and configures all the "root" CMakeLists.txt files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace.
You can also view your projects organized logically by targets. Choose Targets view from the dropdown in the Solution Explorer toolbar:
Visual Studio uses a file called CMakeSettings.json to store environment variables or command-line options for CMake. CMakeSettings.json also enables you to define and store multiple CMake build configurations. You can conveniently switch between them in the IDE.
Otherwise, use the CMakeLists.txt just as you would in any CMake project to specify source files, find libraries, set compiler and linker options, and specify other build system-related information.
If you need to pass arguments to an executable at debug time, you can use another file called launch.vs.json. In some scenarios, Visual Studio automatically generates these files. You can edit them manually, or even create the file yourself.
For other kinds of Open Folder projects, two additional JSON files are used: CppProperties.json and tasks.vs.json. Neither of these are relevant for CMake projects.
Import an existing cache
When you import an existing CMakeCache.txt file, Visual Studio automatically extracts customized variables and creates a pre-populated CMakeSettings.json file based on them. The original cache isn't modified in any way. It can still be used from the command line, or with whatever tool or IDE used to generate it. The new CMakeSettings.json file is placed alongside the project's root CMakeLists.txt. Visual Studio generates a new cache based the settings file. You can override automatic cache generation in the Tools > Options > CMake > General dialog.
Not everything in the cache is imported. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE.
To import an existing cache
From the main menu, choose File > Open > CMake:
This command brings up the Import CMake from Cache wizard.
Navigate to the CMakeCache.txt file that you want to import, and then choose OK. The Import CMake Project from Cache wizard appears:
When the wizard completes, you can see the new CMakeCache.txt file in Solution Explorer next to the root CMakeLists.txt file in your project.
Building CMake projects
To build a CMake project, you have these choices:
In the General toolbar, find the Configurations dropdown. It's probably showing "Linux-Debug" or "x64-Debug" by default. Select the preferred configuration and press F5, or choose the Run (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution.
Right-click on CMakeLists.txt in Solution Explorer and select Build from the context menu. If you have multiple targets in your folder structure, you can choose to build all or only one specific target.
From the main menu, select Build > Build Solution (F7 or Ctrl+Shift+B). Make sure that a CMake target is already selected in the Startup Item dropdown in the General toolbar.
You can customize build configurations, environment variables, command-line arguments, and other settings in the CMakeSettings.json file. It lets you make changes without modifying the CMakeLists.txt file. For more information, see Customize CMake settings.
As you would expect, build results are shown in the Output Window and Error List.
In a folder with multiple build targets, you can specify which CMake target to build: Choose the Build item on the CMake menu or the CMakeLists.txt context menu to specify the target. If you enter Ctrl+Shift+B in a CMake project, it builds the current active document.
Debugging CMake projects
To debug a CMake project, choose the preferred configuration and press F5. Or, press the Run button in the toolbar. If the Run button says "Select Startup Item", select the dropdown arrow and choose the target that you want to run. (In a CMake project, the "Current document" option is only valid for .cpp files.)
The Run or F5 commands first build the project if changes have been made since the previous build.
You can customize a CMake debugging session by setting properties in the launch.vs.json file. For more information, see Configure CMake debugging sessions.
Editing CMakeLists.txt files
To edit a CMakeLists.txt file, right-click on the file in Solution Explorer and choose Open. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about CMakeLists.txt, see the CMake documentation.
As soon as you save the file, the configuration step automatically runs again and displays information in the Output window. Errors and warnings are shown in the Error List or Output window. Double-click on an error in the Error List to navigate to the offending line in CMakeLists.txt.
When significant changes are made to the CMakeSettings.json or to CMakeLists.txt files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations.
Multiple CMake projects may use the same CMake configuration name (for example, x86-Debug). All of them are configured and built (in their own build root folder) when that configuration is selected. You can debug the targets from all of the CMake projects that participate in that CMake configuration.
You can limit builds and debug sessions to a subset of the projects in the workspace. Create a new configuration with a unique name in the CMakeSettings.json file. Then, apply the configuration to those projects only. When that configuration is selected, IntelliSense and the build and debug commands only apply to those specified projects.
Troubleshooting CMake cache errors
If you need more information about the state of the CMake cache to diagnose a problem, open the CMake main menu or the CMakeLists.txt context menu in Solution Explorer to run one of these commands:
View Cache opens the CMakeCache.txt file from the build root folder in the editor. (Any edits you make here to CMakeCache.txt are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see Customize CMake settings.)
Open Cache Folder opens an Explorer window to the build root folder.
Clean Cache deletes the build root folder so that the next CMake configure step starts from a clean cache.
Generate Cache forces the generate step to run even if Visual Studio considers the environment up to date.
Automatic cache generation can be disabled in the Tools > Options > CMake > General dialog.
Single file compilation
To build a single file in a CMake project, right-click on the file in Solution Explorer. Choose Compile from the pop-up menu. You can also build the currently open file in the editor by using the main CMake menu:
Run CMake from the command line
If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps:
Run the appropriate vsdevcmd.bat file (x86/x64). For more information, see Building on the Command Line.
Switch to your output folder.
Run CMake to build or configure your app.
In Visual Studio 2015, Visual Studio users can use a CMake generator to generate MSBuild project files, which the IDE then consumes for IntelliSense, browsing, and compilation.
See also
Tutorial: Create C++ cross-platform projects in Visual Studio
Configure a Linux CMake project
Connect to your remote Linux computer
Customize CMake build settings
CMakeSettings.json schema reference
Configure CMake debugging sessions
Deploy, run, and debug your Linux project
CMake predefined configuration reference
