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

11 files changed, 68 insertions, 5 deletions

diff --git a/Help/envvar/CMAKE_GENERATOR.rst b/Help/envvar/CMAKE_GENERATOR.rst
new file mode 100644
index 0000000..f2d055f
--- /dev/null
+++ b/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`
diff --git a/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst b/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst
new file mode 100644
index 0000000..1654fa1
--- /dev/null
+++ b/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.
diff --git a/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst
new file mode 100644
index 0000000..917b30b
--- /dev/null
+++ b/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.
diff --git a/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst
new file mode 100644
index 0000000..7ac3856
--- /dev/null
+++ b/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.
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 64fd816..810aaa9 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/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.
 
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index c433412..89c9119 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/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
diff --git a/Help/release/dev/default-generator-env.rst b/Help/release/dev/default-generator-env.rst
new file mode 100644
index 0000000..3f20475
--- /dev/null
+++ b/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.
diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst
index cce04c1..ec52cd4 100644
--- a/Help/variable/CMAKE_GENERATOR.rst
+++ b/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.
diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
index 78c81b1..3657ed4 100644
--- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
+++ b/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`
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index 963f0a4..2c115a3 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/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`
diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
index e77f211..a01a8b7 100644
--- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
+++ b/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.