Merge topic 'env-init-configs'

ef56eefc9b cmake: Allow CMAKE_CONFIGURATION_TYPES to be set by environment variable
e216b9bbd3 cmake: Allow CMAKE_BUILD_TYPE to be set by environment variable
6986a382a9 Help: Document when CMAKE_BUILD_TYPE and CMAKE_CONFIGURATION_TYPES are set
e96169a3ec Help: Cross-reference CMAKE_CONFIGURATION_TYPES from CMAKE_BUILD_TYPE
03bd9c4c10 cmMakefile: Add helper to initialize CMAKE_CONFIGURATION_TYPES

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6291

6 files changed, 47 insertions, 0 deletions

diff --git a/Help/envvar/CMAKE_BUILD_TYPE.rst b/Help/envvar/CMAKE_BUILD_TYPE.rst
new file mode 100644
index 0000000..f798aff
--- /dev/null
+++ b/Help/envvar/CMAKE_BUILD_TYPE.rst
@@ -0,0 +1,10 @@
+CMAKE_BUILD_TYPE
+----------------
+
+.. versionadded:: 3.22
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value
+for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit
+configuration given on the first run while creating a new build tree.
diff --git a/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst
new file mode 100644
index 0000000..833aa4a
--- /dev/null
+++ b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst
@@ -0,0 +1,11 @@
+CMAKE_CONFIGURATION_TYPES
+-------------------------
+
+.. versionadded:: 3.22
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a
+default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable
+when there is no explicit configuration given on the first run while
+creating a new build tree.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index fa38588..3db189e 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -30,6 +30,8 @@ Environment Variables that Control the Build
 
    /envvar/CMAKE_APPLE_SILICON_PROCESSOR
    /envvar/CMAKE_BUILD_PARALLEL_LEVEL
+   /envvar/CMAKE_BUILD_TYPE
+   /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CONFIG_TYPE
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
    /envvar/CMAKE_GENERATOR
diff --git a/Help/release/dev/env-init-configs.rst b/Help/release/dev/env-init-configs.rst
new file mode 100644
index 0000000..5c9892d
--- /dev/null
+++ b/Help/release/dev/env-init-configs.rst
@@ -0,0 +1,9 @@
+env-init-configs
+----------------
+
+* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to
+  provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable.
+
+* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to
+  provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES`
+  variable.
diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst
index 405f7d5..9ad1481 100644
--- a/Help/variable/CMAKE_BUILD_TYPE.rst
+++ b/Help/variable/CMAKE_BUILD_TYPE.rst
@@ -23,3 +23,12 @@ Note that configuration names are case-insensitive.  The value of this
 variable will be the same as it is specified when invoking CMake.
 For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the
 value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``.
+
+This variable is initialized by the first :command:`project` or
+:command:`enable_language` command called in a project when a new build
+tree is first created.  If the :envvar:`CMAKE_BUILD_TYPE` environment
+variable is set, its value is used.  Otherwise, a toolchain-specific
+default is chosen when a language is enabled.
+
+See :variable:`CMAKE_CONFIGURATION_TYPES` for specifying the configuration
+with multi-config generators.
diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst
index 8fcc798..5298a72 100644
--- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst
+++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst
@@ -8,5 +8,11 @@ such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc.  This has reasonable
 defaults on most platforms, but can be extended to provide other build
 types.
 
+This variable is initialized by the first :command:`project` or
+:command:`enable_language` command called in a project when a new build
+tree is first created.  If the :envvar:`CMAKE_CONFIGURATION_TYPES`
+environment variable is set, its value is used.  Otherwise, the default
+value is generator-specific.
+
 See :variable:`CMAKE_BUILD_TYPE` for specifying the configuration with
 single-config generators.