Documented cmaketoolchain:extra_variables (#16229)

reference/config_files/global_conf.rst

@@ -143,6 +143,8 @@ All the values will be interpreted by Conan as the result of the python built-in
     tools.microsoft.msbuildtoolchain:compile_options={"ExceptionHandling": "Async"}
 
 
+.. _configuration_data_operators:
+
 Configuration data operators
 ----------------------------
 

reference/tools/cmake/cmaketoolchain.rst

@@ -625,6 +625,26 @@ CMakeToolchain is affected by these ``[conf]`` variables:
 - **tools.cmake.cmaketoolchain:system_name** is not necessary in most cases and is only used to force-define ``CMAKE_SYSTEM_NAME``.
 - **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:extra_variables**: dict-like python object which specifies the CMake variable name and value. Value can be a plain string, number or a dict-like python object which must specifies ``value`` (string/number) , ``cache`` (boolean), ``type`` (CMake cache type) and optionally, ``docstring`` (string: defaulted to variable name). Potential override of CMakeToolchain defined variables, users are at their own risk. E.g.
+
+.. code-block:: text
+
+    [conf]
+    tools.cmake.cmaketoolchain:extra_variables*={'STR': 'string value', 'NUM': 1.3, 'CMAKE_GENERATOR_INSTANCE': '${ENV}/buildTools/', 'SOME_DICT': {'value': '42 sense', 'cache': True, 'type': 'BOOL', 'docstring': 'test cache var'}}
+
+Resulting in:
+
+.. code-block:: cmake
+
+    set(STR "string value")
+    set(NUM 1.3)
+    set(CMAKE_GENERATOR_INSTANCE "${ENV}/buildTools/")
+    set(SOME_DICT "42 sense" CACHE BOOL "test cache var")
+
+.. tip::
+
+    Use the ``*=`` operator described in :ref:`configuration data operators <configuration_data_operators>` to update the dictionary merging it with previous definitions of ``extra_variables``.
+
 - **tools.cmake.cmaketoolchain:toolset_arch**: Will add the ``,host=xxx`` specifier in the ``CMAKE_GENERATOR_TOOLSET`` variable of ``conan_toolchain.cmake`` file.
 - **tools.cmake.cmaketoolchain:toolset_cuda**: (Experimental) Will add the ``,cuda=xxx`` specifier in the ``CMAKE_GENERATOR_TOOLSET`` variable of ``conan_toolchain.cmake`` file.
 - **tools.cmake.cmake_layout:build_folder_vars**: Settings, Options, and/or ``self.name`` and ``self.version`` that will produce a different build folder and different CMake presets names.
@@ -653,4 +673,4 @@ CMakeToolchain is affected by these ``[conf]`` variables:
   * ``fortran``: will set ``CMAKE_Fortran_COMPILER`` in *conan_toolchain.cmake*.
   * ``asm``: will set ``CMAKE_ASM_COMPILER`` in *conan_toolchain.cmake*.
   * ``hip``: will set ``CMAKE_HIP_COMPILER`` in *conan_toolchain.cmake*.
-  * ``ispc``: will set ``CMAKE_ISPC_COMPILER`` in *conan_toolchain.cmake*.
+  * ``ispc``: will set ``CMAKE_ISPC_COMPILER`` in *conan_toolchain.cmake*.