elexer thekla laurice

0 views

Skip to first unread message

Cara Canellas

unread,

Aug 2, 2024, 11:27:42 PM8/2/24

to almajetria

CMake is a cross-platform, open-source tool for defining build processes that run on multiple platforms. This article assumes you're familiar with CMake. For more information about CMake, see the CMake documentation. The CMake tutorial is a good starting point to learn more.

CMake has become more and more integrated with Visual Studio over the past few releases. To see the documentation for your preferred version of Visual Studio, use the Version selector control. It's found at the top of the table of contents on this page.

Visual Studio's native support for CMake enables you to edit, build, and debug CMake projects on Windows, the Windows Subsystem for Linux (WSL), and remote systems from the same instance of Visual Studio. CMake project files (such as CMakeLists.txt) are consumed directly by Visual Studio for the purposes of IntelliSense and browsing. cmake.exe is invoked directly by Visual Studio for CMake configuration and build.

Visual Studio runs CMake and generates the CMake cache file (CMakeCache.txt) for the default configuration. 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.

Starting in Visual Studio 2022 version 17.1 Preview 2, if your top-level CMakeLists.txt exists in a subfolder and not at the root of the workspace, you'll be prompted whether you'd like to enable CMake integration or not. For more information, see CMake partial activation.

Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose the Select View button on the Solution Explorer toolbar. From the list in Solution Explorer - Views, select CMake Targets View and press Enter to open the targets view:

Use the CMakeLists.txt file in each project folder just as you would in any CMake project. You can specify source files, find libraries, set compiler and linker options, and specify other build system-related information. For more information on CMake language services provided by Visual Studio, see Editing CMakeLists.txt files.

To pass arguments to an executable at debug time, you can use another file called launch.vs.json. For more information on debugging cross-platform CMake projects in Visual Studio, see Debugging CMake projects.

The CMake configure step generates the project build system. It's equivalent to invoking cmake.exe from the command line. For more information on the CMake configure step, see the CMake documentation.

Visual Studio uses a CMake configuration file to drive CMake generation and build. CMakePresets.json is supported by Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. CMakePresets.json is supported directly by CMake and can be used to drive CMake generation and build from Visual Studio, from VS Code, in a Continuous Integration pipeline, and from the command line on Windows, Linux, and Mac. For more information on CMakePresets.json, see Configure and build with CMake Presets. CMakeSettings.json is available for customers using an earlier version of Visual Studio. For more information on CMakeSettings.json, see Customize CMake build settings.

When you make significant changes to your CMake configuration file or a CMakeLists.txt file, Visual Studio will automatically run the CMake configure step. You can invoke the configure step manually: Select Project > Configure Cache from the toolbar. You can also change your configuration preferences in Tools > Options > CMake > General.

If you need more information about the state of the CMake cache to diagnose a problem, open the Project main menu or the CMakeLists.txt context menu in Solution Explorer to run one of these commands:

View CMakeCache.txt opens the CMakeCache.txt file from the build directory 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 you clean the cache, see Customize CMake settings or Configure and build with CMake Presets.

The CMake build step builds an already generated project binary tree. It's equivalent to invoking cmake --build from the command line. For more information on the CMake build step, see the CMake documentation.

In the toolbar, find the Startup Item dropdown. Select the preferred target and press F5, or choose the Run button on the toolbar. The project automatically builds first, just like a Visual Studio solution.

Visual Studio uses a CMake configuration file to drive CMake builds. CMake configuration files encapsulate build options like native build tool switches and environment variables. If CMakePresets.json is your active configuration file, see Configure and build with CMake Presets. If CMakeSettings.json is your active configuration file, see Customize CMake build settings. CMakePresets.json is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file.

All executable CMake targets are shown in the Startup Item dropdown in the toolbar. To start debugging, select one and press the Debug > Start Debugging button in the toolbar. In a CMake project, the "Current document" option is only valid for .cpp files.

The Debug or F5 commands first build the project if changes have been made since the previous build. Changes to the CMake configuration file (CMakePresets.json or CMakeSettings.json) or a CMakeLists.txt causes the CMake cache to be regenerated.

You can customize a CMake debugging session by setting properties in the launch.vs.json file. To customize debug settings for a specific target, select the target in the Startup Item dropdown and press Debug > Debug and Launch Settings for . For more information on CMake debugging sessions, see Configure CMake debugging sessions.

When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. To change the Just My Code setting, go to Tools > Options > Debugging > General. For more information on Just My Code debugging, see Debug only user code with Just My Code.

When you build for Windows with the MSVC compiler, CMake projects have support for Edit and Continue. Add the following code to your CMakeLists.txt file to enable Edit and Continue. For more information on Edit and Continue, see Configure Edit and Continue (C#, VB, C++).

Visual Studio allows you to debug a process running on a remote Linux system or WSL and debug it with the GDB debugger. To get started, select Debug > Attach to Process..., set the Connection type to SSH, and select your Connection target from the list of connections in the Connection Manager. Select a process from the list of available processes and press Attach. GDB must be installed on your Linux machine. For more information on SSH connections, see the Connection Manager

In Visual Studio 2022 version 17.1 and later, CMake functionality won't be enabled automatically if your root folder doesn't contain a CMakeLists.txt file. Instead, a dialog will prompt you on whether you'd like to enable CMake functionality for your project. If you decline, CMake cache generation won't start and CMake configurations (from CMakeSettings.json or CMakePresets.json) won't appear in the configuration dropdown. If you accept, you'll be taken to a workspace-level configuration file, CMakeWorkspaceSettings.json (stored in the .vs directory), to specify the folders you'd like to enable CMake for. (These folders contain your root CMakeLists.txt files).

When you open an existing CMake cache file (CMakeCache.txt), Visual Studio doesn't try to manage your cache and build tree for you. Your custom or preferred tools have complete control over how CMake configures your project.

The default existing cache experience relies on cmake-server, which was removed from CMake in version 3.20. To continue using existing cache functionality in Visual Studio 2019 version 16.10 and later, take one of these steps:

Visual Studio uses the CMake file-based API (in versions 3.14 and later) to populate the editor with information specific to your project structure. For more information, see the C++ team blog post on multi-root workspaces and file-based API.

Before generating the CMake cache, your custom or preferred tools might need to create a query file named .cmake/api/v1/query/client-MicrosoftVS/query.json in your build output folder (the folder that contains CMakeCache.txt). The query file should contain this content:

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.

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.

It contains the lines project (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp), and install (TARGETS hello DESTINATION hello/bin). A message at the top of the window says that c plus plus IntelliSense info will refresh after C Make finishes generating the cache.