Add environment information to CMakePresets docs (#3488)

* add docs

* add conf

* minor changes

* Update reference/tools/cmake/cmaketoolchain.rst

reference/commands/config.rst

@@ -238,6 +238,7 @@ Displays all the Conan built-in configurations. There are 2 groups:
     tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
     tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
     tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
+    tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'.
     tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
     tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
     tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
@@ -256,8 +257,8 @@ Displays all the Conan built-in configurations. There are 2 groups:
     tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts
     tools.gnu:make_program: Indicate path to make program
     tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper
-    tools.google.bazel:bazelrc_path: Defines Bazel rc-path
-    tools.google.bazel:configs: Define Bazel config file
+    tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build'
+    tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...'
     tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default)
     tools.info.package_id:confs: List of existing configuration to be part of the package ID
     tools.intel:installation_path: Defines the Intel oneAPI installation root path
@@ -269,9 +270,10 @@ Displays all the Conan built-in configurations. There are 2 groups:
     tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu
     tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable
     tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects
-    tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler
+    tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default
     tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns
     tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options
+    tools.microsoft:winsdk_version: Use this winsdk_version in vcvars
     tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install'
     tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default)
     tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default)

reference/config_files/global_conf.rst

@@ -85,6 +85,7 @@ To list all the possible configurations available, run :command:`conan config li
     tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
     tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
     tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
+    tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'.
     tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
     tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
     tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
@@ -103,8 +104,8 @@ To list all the possible configurations available, run :command:`conan config li
     tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts
     tools.gnu:make_program: Indicate path to make program
     tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper
-    tools.google.bazel:bazelrc_path: Defines Bazel rc-path
-    tools.google.bazel:configs: Define Bazel config file
+    tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build'
+    tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...'
     tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default)
     tools.info.package_id:confs: List of existing configuration to be part of the package ID
     tools.intel:installation_path: Defines the Intel oneAPI installation root path
@@ -116,9 +117,10 @@ To list all the possible configurations available, run :command:`conan config li
     tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu
     tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable
     tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects
-    tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler
+    tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default
     tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns
     tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options
+    tools.microsoft:winsdk_version: Use this winsdk_version in vcvars
     tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install'
     tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default)
     tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default)

reference/tools/cmake/cmaketoolchain.rst

@@ -67,23 +67,40 @@ translated from the current ``settings``:
   so defining the correct Visual Studio prompt is easier.
 
 
-- **CMakePresets.json**: The toolchain also generates a ``CMakePresets.json`` standard file, check the documentation
-  `here <https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html>`_. It is currently using the version "3" of
-  the JSON schema.
-  Conan creates a ``conan-default`` configure preset with the information:
-
-     - The ``generator`` to be used.
-     - The path to the ``conan_toolchain.cmake``.
-     - Some cache variables corresponding to the specified settings cannot work if specified in the toolchain.
-     - The ``CMAKE_BUILD_TYPE`` variable when using a single-configuration generators.
-     - The ``BUILD_TESTING`` variable set to ``OFF``, when configuration ``tools.build:skip_test`` is true.
-     - If you run several ``conan install`` with different ``-s build_type`` values, it will generate the corresponding
-       ``buildPresets`` and ``configurePresets``.
-     - By default, the presets names will be ``conan-xxxx``, but the "conan-" prefix can be customized with 
-       ``CMakeToolchain.presets_prefix = "conan"`` attribute.
-     - The preset names will be controlled by the ``layout()`` ``self.folders.build_folder_vars`` definition, that
-       can contain a list of settings and options like ``["settings.compiler", "settings.arch", "options.shared"]``.
-
+- **CMakePresets.json**: This toolchain generates a standard `CMakePresets.json` file. For
+  more information, refer to the documentation `here
+  <https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html>`_. It currently uses
+  version "3" of the JSON schema. Conan adds *configure*, *build*, and *test* preset
+  entries to the JSON file:
+
+    - `configurePresets` storing the following information:
+        - The `generator` to be used.
+        - The path to the `conan_toolchain.cmake`.
+        - Cache variables corresponding to the specified settings that cannot work if
+          specified in the toolchain.
+        - The `CMAKE_BUILD_TYPE` variable for single-configuration generators.
+        - The `BUILD_TESTING` variable set to `OFF` when the configuration
+          `tools.build:skip_test` is true.
+        - An environment section setting all the environment information related to the
+          :ref:`VirtualBuildEnv<conan_tools_env_virtualbuildenv>` (if any). You can skip
+          the generation of this section by using the
+          ``tools.cmake.cmaketoolchain:presets_environment`` configuration.
+        - By default, preset names will be `conan-xxxx`, but the "conan-" prefix can be
+          customized with the `CMakeToolchain.presets_prefix = "conan"` attribute.
+        - Preset names are controlled by the `layout()` `self.folders.build_folder_vars`
+          definition, which can contain a list of settings and options like
+          `["settings.compiler", "settings.arch", "options.shared"]`.
+
+    - `buildPresets` storing the following information:
+        - The `configurePreset` associated with this build preset.
+
+    - `testPresets` storing the following information:
+        - The `configurePreset` associated with this build preset.
+        - An environment section setting all the environment information related to the
+          :ref:`VirtualRunEnv<conan_tools_env_virtualrunenv>` (if any). You can skip the
+          generation of this section by using the
+          ``tools.cmake.cmaketoolchain:presets_environment`` configuration.
+
 
 - **CMakeUserPresets.json**:  If you declare a ``layout()`` in the recipe and your
   ``CMakeLists.txt`` file is found at the ``conanfile.source_folder`` folder, a
@@ -99,8 +116,10 @@ translated from the current ``settings``:
   you can define ``tc.user_presets_path = "ConanPresets.jon"`` in the ``generate()`` method.
   See :ref:`extending your own CMake presets<examples-tools-cmake-toolchain-build-project-extend-presets>` for a full example.
 
-  Note: Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not
+  **Note:** Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not
   generated by Conan.
+
+  **Note:** To list all available presets, use the ``cmake --list-presets`` command:
 
 .. note::
 
@@ -504,6 +523,7 @@ CMakeToolchain is affected by these ``[conf]`` variables:
 - **tools.cmake.cmaketoolchain:system_processor** is not necessary in most cases and is only used to force-define ``CMAKE_SYSTEM_PROCESSOR``.
 - **tools.cmake.cmaketoolchain:toolset_arch**: Will add the ``,host=xxx`` specifier in the ``CMAKE_GENERATOR_TOOLSET`` variable of ``conan_toolchain.cmake`` file.
 - **tools.cmake.cmake_layout:build_folder_vars**: Settings and Options that will produce a different build folder and different CMake presets names.
+- **tools.cmake.cmaketoolchain:presets_environment**: Set to ``'disabled'`` to prevent the addition of the environment section to the generated CMake presets.
 - **tools.build:cxxflags** list of extra C++ flags that will be appended to ``CMAKE_CXX_FLAGS_INIT``.
 - **tools.build:cflags** list of extra of pure C flags that will be appended to ``CMAKE_C_FLAGS_INIT``.
 - **tools.build:sharedlinkflags** list of extra linker flags that will be appended to ``CMAKE_SHARED_LINKER_FLAGS_INIT``.