Merge pull request #3600 from MicrosoftDocs/master

6/4/2021 AM Publish

Author: Taojunshen

docs/build/cmake-presets-json-reference.md

@@ -68,7 +68,7 @@ Options for a `remotePrebuildEvent` and `remotePostbuildEvent` have been depreca
 
  Encode pre-build, pre-link, and post-build events in your CMakeLists.txt using [add_custom_command](https://cmake.org/cmake/help/latest/command/add_custom_command.html#build-events). This will ensure the same behavior when building with Visual Studio and from the command line.
 
-If you need behavior that is specific to Visual Studio, you can add a custom remote task in` tasks.vs.json`. To get started, right-click on your root `CMakeLists.txt` in the **Solution Explorer** from **Folder View** and select **Configure Tasks**.  You can then [add a new remote task](/cpp/build/tasks-vs-json-schema-reference-cpp#remote-properties) to your `tasks.vs.json` file.
+If you need behavior that is specific to Visual Studio, you can add a custom remote task in` tasks.vs.json`. To get started, right-click on your root `CMakeLists.txt` in the **Solution Explorer** from **Folder View** and select **Configure Tasks**.  You can then [add a new remote task](./tasks-vs-json-schema-reference-cpp.md#remote-properties) to your `tasks.vs.json` file.
 
 The following remote task creates a directory called test on the remote Linux system:
 

docs/build/cmake-presets-vs.md

@@ -388,7 +388,7 @@ If you've identified a problem, the best way to report it is by selecting the **
 
 ## Enable logging for remote connections
 
-You can enable logging for remote connections if you're having trouble connecting or copying files to a remote system. For more information, see [Logging for remote connections](/cpp/linux/connect-to-your-remote-linux-computer#logging-for-remote-connections).
+You can enable logging for remote connections if you're having trouble connecting or copying files to a remote system. For more information, see [Logging for remote connections](../linux/connect-to-your-remote-linux-computer.md#logging-for-remote-connections).
 
 ## Enable AddressSanitizer for Windows and Linux
 
@@ -411,7 +411,7 @@ if(ASAN_ENABLED)
 endif()
 ```
 
-The `<additional-options>` part lists other compilation flags, like `"-fno-omit-frame-pointer"`. For more information about AddressSanitizer for Linux, see [Using AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer#using-addresssanitizer). For more information about using AddressSanitizer with the Microsoft Visual C++ (MSVC) compiler, see [Use AddressSanitizer from a developer command prompt](/cpp/sanitizers/asan#command-prompt).
+The `<additional-options>` part lists other compilation flags, like `"-fno-omit-frame-pointer"`. For more information about AddressSanitizer for Linux, see [Using AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer#using-addresssanitizer). For more information about using AddressSanitizer with the Microsoft Visual C++ (MSVC) compiler, see [Use AddressSanitizer from a developer command prompt](../sanitizers/asan.md#command-prompt).
 
 Pass runtime flags to AddressSanitizer by using the `ASAN_OPTIONS` field in `launch.vs.json`. `ASAN_OPTIONS` defaults to `detect_leaks=0` when no other runtime options are specified because LeakSanitizer isn't supported in Visual Studio.
 
@@ -421,7 +421,7 @@ You can use the same `CMakePresets.json` and `CMakeUserPresets.json` files to in
 
 ### Sourcing the environment when building with command-line generators on Windows
 
-It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Visual C++ toolset on Windows, set the environment before CMake is called to generate the build system. You can do it by calling `vcvarsall.bat` with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](/cpp/build/building-on-the-command-line#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step.
+It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Visual C++ toolset on Windows, set the environment before CMake is called to generate the build system. You can do it by calling `vcvarsall.bat` with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](./building-on-the-command-line.md#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step.
 
 It's the same step that Visual Studio takes for you when the IDE invokes CMake. Visual Studio parses the active Configure Preset for the host and target architecture specified by `toolset` and `architecture`. Visual Studio then sources the specified environment from `vcvarsall.bat`. When you build from the Windows command line with Ninja, you'll need to take this step yourself.
 
@@ -451,4 +451,4 @@ Learn more about configuring and debugging CMake projects in Visual Studio:
 > [Customize CMake build settings](customize-cmake-settings.md)<br/><br/>
 > [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)<br/><br/>
 > [CMake predefined configuration reference](cmake-predefined-configuration-reference.md)
->
+>

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

@@ -63,6 +63,18 @@ When you open an existing CMake cache file (*CMakeCache.txt*), Visual Studio doe
 
 You can add an existing CMake cache to an open project. It's done the same way you'd add a new configuration. For more information, see our blog post on [opening an existing cache in Visual Studio](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/).
 
+### Advanced CMake cache troubleshooting
+
+Visual Studio uses CMake's [file-based API](https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html) (in CMake 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](https://devblogs.microsoft.com/cppblog/visual-studio-code-cmake-tools-extension-multi-root-workspaces-and-file-based-api/).
+
+Before generating the CMake cache, your custom or preferred tools may 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:
+
+```json
+{"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.
+
 ## Building CMake projects
 
 To build a CMake project, you have these choices: