Documented usage of force option on tools.cmake.cmaketoolchain:extra_variables (#3774)

Co-authored-by: Rubén Rincón Blanco <[email protected]>

Author: perseoGI

reference/tools/cmake/cmaketoolchain.rst

@@ -653,7 +653,7 @@ 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.
+- **tools.cmake.cmaketoolchain:extra_variables**: dict-like python object which specifies the CMake variable name and value. The value can be a plain string, a number or a dict-like python object which must specify the ``value`` (string/number) , ``cache`` (boolean), ``type`` (CMake cache type) and optionally, ``docstring`` (string: defaulted to variable name) and ``force`` (boolean) keys. It can override CMakeToolchain defined variables, for which users are at their own risk. E.g.
 
 .. code-block:: text
 
@@ -673,15 +673,15 @@ Another advanced usage:
 .. code-block:: text
 
     tools.cmake.cmaketoolchain:extra_variables={'MyIntegerVariable': 42, 'CMAKE_GENERATOR_INSTANCE': '${ENV}/buildTools/'}
-    tools.cmake.cmaketoolchain:extra_variables*={'CACHED_VAR': {'value': '/var/run', 'cache': True, 'type': 'PATH', 'docstring': 'test cache var'}}
+    tools.cmake.cmaketoolchain:extra_variables*={'CACHED_VAR': {'value': '/var/run', 'cache': True, 'type': 'PATH', 'docstring': 'test cache var', 'force': True}}
 
 Resulting in:
 
 .. code-block:: cmake
 
     set(MyIntegerVariable 42)
     set(CMAKE_GENERATOR_INSTANCE "${ENV}/buildTools/")
-    set(CACHED_VAR "/var/run" CACHE BOOL "test cache var")
+    set(CACHED_VAR "/var/run" CACHE BOOL "test cache var" FORCE)
 
 This block injects ``$`` which will be expanded later. It also defines a cache variable of type ``PATH``.