Skip to content

Add section on CMake partial activation #3566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 10, 2021
Merged

Add section on CMake partial activation #3566

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
45dd392
Add section on CMake partial activation
sfreed141 Dec 1, 2021
932758f
Grammar and formatting fixes
Dec 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/build/cmake-projects-in-visual-studio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ When you **open a folder** containing a *`CMakeLists.txt`* file, the following t

- 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.

> [!NOTE]
> Starting in Visual Studio 2022 version 17.1 Preview 2, if your folder doesn't contain a root `CMakeLists.txt` you'll be prompted whether you'd like to enable CMake integration or not. For more information, see [CMake partial activation](#cmake-partial-activation).

Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose **Targets view** from the dropdown in the **Solution Explorer** toolbar:

![CMake targets view button.](media/cmake-targets-view.png)
Expand Down Expand Up @@ -144,6 +147,19 @@ Visual Studio allows you to debug a process running on a remote Linux system or

![A screenshot of the Attach to Process menu](media/attach-to-process.png)

## <a name="cmake-partial-activation"></a> CMake partial activation

Starting in Visual Studio 2022 version 17.1 Preview 2, 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).

The accepted properties are:

| Property | Description |
|--|--|
| `enableCMake` | Enable Visual Studio's integration for this workspace. |
| `sourceDirectory` | A string or array of strings specifying the directory or directories with `CMakeLists.txt`. Macros (such as `${workspaceRoot}`) are allowed. Relative paths are relative to the workspace root. Directories outside of the current workspace will be ignored. |

You can reach `CMakeWorkspaceSettings.json` through the **Project** > **CMake Workspace Settings** menu command at any time, even if CMake functionality is currently disabled.

## Open an existing cache

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.
Expand Down