Help: Add documentation for default generator environment variables

Documentation for environment variables that control the default
generator selection:

* CMAKE_GENERATOR
* CMAKE_GENERATOR_INSTANCE
* CMAKE_GENERATOR_PLATFORM
* CMAKE_GENERATOR_TOOLSET

Help/envvar/CMAKE_GENERATOR.rst

@@ -0,0 +1,16 @@
+CMAKE_GENERATOR
+---------------
+
+.. include:: ENV_VAR.txt
+
+Specifies the CMake default generator to use when no generator is supplied
+with ``-G``. If the provided value doesn't name a generator known by CMake,
+the internal default is used.  Either way the resulting generator selection
+is stored in the :variable:`CMAKE_GENERATOR` variable.
+
+Some generators may be additionally configured using the environment
+variables:
+
+* :envvar:`CMAKE_GENERATOR_PLATFORM`
+* :envvar:`CMAKE_GENERATOR_TOOLSET`
+* :envvar:`CMAKE_GENERATOR_INSTANCE`

Help/envvar/CMAKE_GENERATOR_INSTANCE.rst

@@ -0,0 +1,7 @@
+CMAKE_GENERATOR_INSTANCE
+------------------------
+
+.. include:: ENV_VAR.txt
+
+Default value for :variable:`CMAKE_GENERATOR_INSTANCE` if no Cache entry is
+present. This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

Help/envvar/CMAKE_GENERATOR_PLATFORM.rst

@@ -0,0 +1,8 @@
+CMAKE_GENERATOR_PLATFORM
+------------------------
+
+.. include:: ENV_VAR.txt
+
+Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry
+is present and no value is specified by :manual:`cmake(1)` ``-A`` option.
+This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

Help/envvar/CMAKE_GENERATOR_TOOLSET.rst

@@ -0,0 +1,8 @@
+CMAKE_GENERATOR_TOOLSET
+-----------------------
+
+.. include:: ENV_VAR.txt
+
+Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry
+is present and no value is specified by :manual:`cmake(1)` ``-T`` option.
+This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

Help/manual/OPTIONS_BUILD.txt

@@ -56,6 +56,9 @@
  build system.  Possible generator names are specified in the
  :manual:`cmake-generators(7)` manual.
 
+ If not specified, CMake checks the :envvar:`CMAKE_GENERATOR` environment
+ variable and otherwise falls back to a builtin default selection.
+
 ``-T <toolset-spec>``
  Toolset specification for the generator, if supported.
 

Help/manual/cmake-env-variables.7.rst

@@ -23,6 +23,10 @@ Environment Variables that Control the Build
 
    /envvar/CMAKE_BUILD_PARALLEL_LEVEL
    /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CMAKE_GENERATOR
+   /envvar/CMAKE_GENERATOR_INSTANCE
+   /envvar/CMAKE_GENERATOR_PLATFORM
+   /envvar/CMAKE_GENERATOR_TOOLSET
    /envvar/CMAKE_MSVCIDE_RUN_PATH
    /envvar/CMAKE_NO_VERBOSE
    /envvar/CMAKE_OSX_ARCHITECTURES

Help/release/dev/default-generator-env.rst

@@ -0,0 +1,9 @@
+default-generator-env
+---------------------
+
+* The :envvar:`CMAKE_GENERATOR` environment variable was added
+  to specify a default generator to use when :manual:`cmake(1)` is
+  run without a ``-G`` option.  Additionally, environment variables
+  :envvar:`CMAKE_GENERATOR_PLATFORM`, :envvar:`CMAKE_GENERATOR_TOOLSET`,
+  and :envvar:`CMAKE_GENERATOR_INSTANCE` were created to configure
+  the generator.

Help/variable/CMAKE_GENERATOR.rst

@@ -5,3 +5,8 @@ The generator used to build the project.  See :manual:`cmake-generators(7)`.
 
 The name of the generator that is being used to generate the build
 files.  (e.g.  ``Unix Makefiles``, ``Ninja``, etc.)
+
+The value of this variable should never be modified by project code.
+A generator may be selected via the :manual:`cmake(1)` ``-G`` option,
+interactively in :manual:`cmake-gui(1)`, or via the :envvar:`CMAKE_GENERATOR`
+environment variable.

Help/variable/CMAKE_GENERATOR_INSTANCE.rst

@@ -5,9 +5,10 @@ Generator-specific instance specification provided by user.
 
 Some CMake generators support selection of an instance of the native build
 system when multiple instances are available.  If the user specifies an
-instance (e.g. by setting this cache entry), or after a default instance is
-chosen when a build tree is first configured, the value will be available in
-this variable.
+instance (e.g. by setting this cache entry or via the
+:envvar:`CMAKE_GENERATOR_INSTANCE` environment variable), or after a default
+instance is chosen when a build tree is first configured, the value will be
+available in this variable.
 
 The value of this variable should never be modified by project code.
 A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`

Help/variable/CMAKE_GENERATOR_PLATFORM.rst

@@ -6,7 +6,8 @@ Generator-specific target platform specification provided by user.
 Some CMake generators support a target platform name to be given
 to the native build system to choose a compiler toolchain.
 If the user specifies a platform name (e.g. via the :manual:`cmake(1)` ``-A``
-option) the value will be available in this variable.
+option or via the :envvar:`CMAKE_GENERATOR_PLATFORM` environment variable)
+the value will be available in this variable.
 
 The value of this variable should never be modified by project code.
 A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`

Help/variable/CMAKE_GENERATOR_TOOLSET.rst

@@ -5,7 +5,8 @@ Native build system toolset specification provided by user.
 
 Some CMake generators support a toolset specification to tell the
 native build system how to choose a compiler.  If the user specifies
-a toolset (e.g.  via the :manual:`cmake(1)` ``-T`` option) the value
+a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option or via
+the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value
 will be available in this variable.
 
 The value of this variable should never be modified by project code.