Merge pull request #3566 from sfreed141/patch-3

Add section on CMake partial activation

Author: Colin Robertson

docs/build/cmake-projects-in-visual-studio.md

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