Docs for 11655 (#2666)

reference/conanfile/tools/cmake/cmaketoolchain.rst

@@ -63,6 +63,10 @@ translated from the current ``settings``:
   - Definition of the standard library used for C++
   - Deactivation of rpaths in OSX
 
+- *conanvcvars.bat*: In some cases, the Visual Studio environment needs to be defined correctly for building,
+  like when using the Ninja or NMake generators. If necessary, the ``CMakeToolchain`` will generate this script,
+  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 version "3" of
   the JSON schema.
@@ -76,15 +80,22 @@ translated from the current ``settings``:
 - *CMakeUserPresets.json*:  If you declare a ``layout()`` in the recipe and your ``CMakeLists.txt`` file is found in
   the ``conanfile.source_folder`` folder, Conan will place a ``CMakeUserPresets.json`` to include the ``CMakePresets.json`` 
   generated with the above specification. This will allow your IDE to allow your IDE (Visual Studio, Visual Studio Code, CLion...) 
-  or ``cmake`` tool to locate the  Conan-generated``CMakePresets.json``. The version schema of the generated ``CMakeUserPresets.json`` is 
-  "4" and requires CMake >= 3.23.
-  Note: Conan will skip the generation if it already exists and was not previously generated by Conan.
+  or ``cmake`` tool to locate the  Conan-generated ``CMakePresets.json``.
 
+  Note: Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not
+  generated by Conan.
 
-- *conanvcvars.bat*: In some cases, the Visual Studio environment needs to be defined correctly for building,
-  like when using the Ninja or NMake generators. If necessary, the ``CMakeToolchain`` will generate this script,
-  so defining the correct Visual Studio prompt is easier.
+By default, the version schema of the generated ``CMakeUserPresets.json`` is 4 and the schema for the ``CMakePresets.json`` is 3,
+so they require CMake >= 3.23.
+You can control the version of the generated ``CMakePresets.json`` and ``CMakeUserPresets.json`` with a configuration
+``tools.cmake.cmaketoolchain.presets:max_schema_version``.
+
+It can be set in the :ref:`global.conf<global_conf>` or with `-c` in the :command:`conan install` command.
+The minimum accepted value for this conf is ``2``:
+
+.. code:: bash
 
+  conan install . -c tools.cmake.cmaketoolchain.presets:max_schema_version=2
 
 constructor
 +++++++++++
@@ -309,6 +320,8 @@ conf
 - ``tools.cmake.cmaketoolchain:system_version`` is not necessary in most cases and is only used to force-define ``CMAKE_SYSTEM_VERSION``.
 - ``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:max_schema_version``: Generate CMakeUserPreset.json compatible with the supplied schema version.
 - ``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``.

reference/config_files/global_conf.rst

@@ -44,6 +44,7 @@ To list all possible configurations available, run :command:`conan config list`.
 .. code-block:: text
 
     $ conan config list
+
     core:required_conan_version: Raise if current version does not match the defined range.
     core.package_id:msvc_visual_incompatible: Allows opting-out the fallback from the new msvc compiler to the Visual Studio compiler existing binaries
     core:default_profile: Defines the default host profile ('default' by default)
@@ -59,8 +60,9 @@ To list all possible configurations available, run :command:`conan config list`.
     tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
     tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
     tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
+    tools.cmake.cmaketoolchain.presets:max_schema_version: Generate CMakeUserPreset.json compatible with the supplied schema version
     tools.env.virtualenv:auto_use: Automatically activate virtualenv file generation
-    tools.cmake.cmake_layout.build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
+    tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
     tools.files.download:retry: Number of retries in case of failure when downloading
     tools.files.download:retry_wait: Seconds to wait between download attempts
     tools.gnu:make_program: Indicate path to make program