[llvm] [docs][CMake] Add CMakePreset, improve VS documentation (PR #84760)

[Aaron Ballman via llvm-commits]

================
@@ -119,7 +121,56 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
  Select the last link: ``Source code (zip)`` and unpack the downloaded file using
  Windows Explorer built-in zip support or any other unzip tool.
 
-12. Finally, configure LLVM using CMake:
+12. Open the LLVM folder in Visual Studio or generate a solution via CMake.
+
+  At this point you can select if you want to use the
+  :ref:`native support for CMake<vs_native_cmake>` in Visual Studio or
+  :ref:`generate Visual Studio<gen_vs_cmake>` solution file from CMake.
+  Both integrations are supported in the LLVM project.
+
+.. _vs_native_cmake:
+
+Visual Studio native CMake support
+==================================
+
+Before you can build LLVM with Visual Studio you need to follow the step
+outlined in :ref:`Getting Started<getting_started>`.
+
+Support for native CMake integration was added in Visual Studio 2019, but it has
+been made more robust in 2022. If you are using Visual Studio before 2022, it's
+recommended to generate a Visual Studio solution from CMake instead of using the
+native CMake integration.
+
+If you want to generate a Visual Studio Solution, please refer to the
+chapter below on :ref:generating Visual Studio Solution<gen_vs_cmake>.
+
+To use the native CMake support, launch Visual Studio 2022 and select the option
+Open a Local Folder and open the root llvm-project folder. This will
+automatically launch CMake (have some patience, it can be a bit slow) and
+populate the interface.
+
+LLVM ships with a default CMakePresets.json that is supposed to make it easy to
+get started, but usually you need to modify the settings used. The best way to
+do this is to create a CMakeUserPresets.json in the llvm subfolder and add your
+configuration there. For more information about the Preset system, see
+`Microsoft's documentation <https://learn.microsoft.com/en-us/cpp/build/cmake-presets-json-reference>`_.
----------------
AaronBallman wrote:

I'm confused by this -- I've been using integrated CMake in Visual Studio for a few years now and I've never needed to do this. Rather, I've been going to `Project->CMake Settings for LLVM` which allows me to set the state of various CMake variables. It looks like this:

![Capture](https://github.com/llvm/llvm-project/assets/4587626/266e4d3f-6955-435b-a7c5-a094ab96dfa1)

However, that menu is gone entirely with CMakePresets.json present and the replacement (Project->Edit CMake Presets for LLVM) is less usable. It looks like this:

![Capture2](https://github.com/llvm/llvm-project/assets/4587626/0f519b77-4056-4060-ab3d-65be97177519)

There's a few concerns here:

1) This file silently overrides all of my previous settings which is going to be really surprising to folks who are already using Visual Studio's cmake integration. What I get now is: ` Command line: "C:\WINDOWS\system32\cmd.exe" /c "%SYSTEMROOT%\System32\chcp.com 65001 >NUL && "C:\PROGRAM FILES\MICROSOFT VISUAL STUDIO\2022\PROFESSIONAL\COMMON7\IDE\COMMONEXTENSIONS\MICROSOFT\CMAKE\CMake\bin\cmake.exe"  -G "Ninja"  -DLLVM_ENABLE_PROJECTS:STRING="clang;lld;clang-tools-extra" -DCMAKE_BUILD_TYPE:STRING="Debug" -DCMAKE_CXX_COMPILER:STRING="clang-cl" -DCMAKE_C_COMPILER:STRING="clang-cl" -DLLVM_OPTIMIZED_TABLEGEN:STRING="ON"   -DCMAKE_MAKE_PROGRAM="C:\PROGRAM FILES\MICROSOFT VISUAL STUDIO\2022\PROFESSIONAL\COMMON7\IDE\COMMONEXTENSIONS\MICROSOFT\CMAKE\Ninja\ninja.exe" "F:\source\llvm-project\llvm" 2>&1"`

So it's using a different compiler, building different projects, and different settings. :-(

2) Editing a JSON file is less intuitive than editing from a dialog box, so I think this is a bit of a regression in terms of usability. For example, there's no longer any discoverability of our cmake variables like there was previously:

![Capture3](https://github.com/llvm/llvm-project/assets/4587626/c8c959e8-c0b4-420d-bcd2-2cffa5ac4a78)

3) The default settings are missing some common, important things like number of compile and link jobs to use, enabling IDE support, and (perhaps) exporting compile commands.

Given that users are almost certainly going to have to edit the default settings whether we go with a presets file or not, I think we should drop the presets file so that users can use the more discoverable interface, and instead, we can document how to use the non-presets approach. That will have the least impact on our existing developers, but I also think it gives a better user experience to newcomers because it's a more gentle approach than "edit this JSON file". WDYT?

https://github.com/llvm/llvm-project/pull/84760