Help/ctest: Document remaining script variables for dashboard settings

Some have gone historically "undocumented" in that they are listed in
`ctest(1)` and are intended for public use, but aren't listed in
`cmake-variables(7)` with their own variable pages.

Help/command/ctest_build.rst

@@ -54,7 +54,7 @@ The options are:
 
 ``FLAGS <flags>``
   Pass additional arguments to the underlying build command.
-  If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
+  If not specified the :variable:`CTEST_BUILD_FLAGS` variable will be checked.
   This can, e.g., be used to trigger a parallel build using the
   ``-j`` option of ``make``. See the :module:`ProcessorCount` module
   for an example.
@@ -67,7 +67,7 @@ The options are:
 
 ``TARGET <target-name>``
   Specify the name of a target to build.  If not specified the
-  ``CTEST_BUILD_TARGET`` variable will be checked.  Otherwise the
+  :variable:`CTEST_BUILD_TARGET` variable will be checked.  Otherwise the
   default target will be built.  This is the "all" target
   (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
 

Help/manual/cmake-variables.7.rst

@@ -747,12 +747,17 @@ Variables for CTest
 
    /variable/CTEST_BINARY_DIRECTORY
    /variable/CTEST_BUILD_COMMAND
+   /variable/CTEST_BUILD_FLAGS
    /variable/CTEST_BUILD_NAME
    /variable/CTEST_BUILD_PRESET
+   /variable/CTEST_BUILD_TARGET
    /variable/CTEST_BZR_COMMAND
    /variable/CTEST_BZR_UPDATE_OPTIONS
    /variable/CTEST_CHANGE_ID
    /variable/CTEST_CHECKOUT_COMMAND
+   /variable/CTEST_CMAKE_GENERATOR
+   /variable/CTEST_CMAKE_GENERATOR_PLATFORM
+   /variable/CTEST_CMAKE_GENERATOR_TOOLSET
    /variable/CTEST_CONFIGURATION_TYPE
    /variable/CTEST_CONFIGURE_COMMAND
    /variable/CTEST_CONFIGURE_PRESET
@@ -823,6 +828,7 @@ Variables for CTest
    /variable/CTEST_TEST_PRESET
    /variable/CTEST_TEST_TIMEOUT
    /variable/CTEST_TEST_COVERAGE_TOOL
+   /variable/CTEST_TIME_LIMIT
    /variable/CTEST_TLS_VERIFY
    /variable/CTEST_TLS_VERSION
    /variable/CTEST_UPDATE_COMMAND

Help/manual/ctest.1.rst

@@ -1536,21 +1536,21 @@ Configuration settings include:
   The CMake generator to use for the configure step when
   ``ConfigureCommand`` is not set.
 
-  * `CTest Script`_ variable: ``CTEST_CMAKE_GENERATOR``
+  * `CTest Script`_ variable: :variable:`CTEST_CMAKE_GENERATOR`
   * :module:`CTest` module variable: none
 
 ``CMakeGeneratorPlatform``
   The CMake generator platform to use for the configure step when
   ``ConfigureCommand`` is not set.
 
-  * `CTest Script`_ variable: ``CTEST_CMAKE_GENERATOR_PLATFORM``
+  * `CTest Script`_ variable: :variable:`CTEST_CMAKE_GENERATOR_PLATFORM`
   * :module:`CTest` module variable: none
 
 ``CMakeGeneratorToolset``
   The CMake generator toolset to use for the configure step when
   ``ConfigureCommand`` is not set.
 
-  * `CTest Script`_ variable: ``CTEST_CMAKE_GENERATOR_TOOLSET``
+  * `CTest Script`_ variable: :variable:`CTEST_CMAKE_GENERATOR_TOOLSET`
   * :module:`CTest` module variable: none
 
 .. _`CTest Build Step`:
@@ -1614,14 +1614,14 @@ Configuration settings include:
   Additional flags to pass to the build tool when building the project.
   Only used when ``MakeCommand`` is not set explicitly.
 
-  * `CTest Script`_ variable: ``CTEST_BUILD_FLAGS``
+  * `CTest Script`_ variable: :variable:`CTEST_BUILD_FLAGS`
   * :module:`CTest` module variable: none
 
 ``BuildTarget``
   Specify a specific target to build instead of the default target.
   Only used when ``MakeCommand`` is not set explicitly.
 
-  * `CTest Script`_ variable: ``CTEST_BUILD_TARGET``
+  * `CTest Script`_ variable: :variable:`CTEST_BUILD_TARGET`
   * :module:`CTest` module variable: none
 
 .. _`CTest Test Step`:
@@ -1987,7 +1987,7 @@ Configuration settings include:
   CTest will not start additional steps once the remaining time drops
   below two minutes.
 
-  * `CTest Script`_ variable: ``CTEST_TIME_LIMIT``
+  * `CTest Script`_ variable: :variable:`CTEST_TIME_LIMIT`
   * :module:`CTest` module variable: none
 
 ``TLSVersion``

Help/variable/CTEST_BUILD_FLAGS.rst

@@ -0,0 +1,10 @@
+CTEST_BUILD_FLAGS
+-----------------
+
+Specify the CTest ``BuildFlags`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The :command:`ctest_build` command passes these flags to the native
+build tool when :variable:`CTEST_BUILD_COMMAND` is not set.  The
+``FLAGS`` option of the command takes priority over this variable.

Help/variable/CTEST_BUILD_TARGET.rst

@@ -0,0 +1,10 @@
+CTEST_BUILD_TARGET
+------------------
+
+Specify the CTest ``BuildTarget`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The :command:`ctest_build` command builds this target instead of the
+default target when :variable:`CTEST_BUILD_COMMAND` is not set.  The
+``TARGET`` option of the command takes priority over this variable.

Help/variable/CTEST_CMAKE_GENERATOR.rst

@@ -0,0 +1,14 @@
+CTEST_CMAKE_GENERATOR
+---------------------
+
+Specify the CTest ``CMakeGenerator`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The :command:`ctest_configure` command passes this generator to
+:manual:`cmake(1)` when :variable:`CTEST_CONFIGURE_COMMAND` is not set.
+The :command:`ctest_build` command also uses it to compute the build
+command line when :variable:`CTEST_BUILD_COMMAND` is not set.
+
+See also :variable:`CTEST_CMAKE_GENERATOR_PLATFORM` and
+:variable:`CTEST_CMAKE_GENERATOR_TOOLSET`.

Help/variable/CTEST_CMAKE_GENERATOR_PLATFORM.rst

@@ -0,0 +1,12 @@
+CTEST_CMAKE_GENERATOR_PLATFORM
+------------------------------
+
+Specify the CTest ``CMakeGeneratorPlatform`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The :command:`ctest_configure` command passes this value to
+:manual:`cmake(1)` with the :cmake-option:`-A` option when
+:variable:`CTEST_CONFIGURE_COMMAND` is not set.  See
+:variable:`CMAKE_GENERATOR_PLATFORM` for the values supported by each
+generator.

Help/variable/CTEST_CMAKE_GENERATOR_TOOLSET.rst

@@ -0,0 +1,12 @@
+CTEST_CMAKE_GENERATOR_TOOLSET
+-----------------------------
+
+Specify the CTest ``CMakeGeneratorToolset`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The :command:`ctest_configure` command passes this value to
+:manual:`cmake(1)` with the :cmake-option:`-T` option when
+:variable:`CTEST_CONFIGURE_COMMAND` is not set.  See
+:variable:`CMAKE_GENERATOR_TOOLSET` for the values supported by each
+generator.

Help/variable/CTEST_TIME_LIMIT.rst

@@ -0,0 +1,13 @@
+CTEST_TIME_LIMIT
+----------------
+
+Specify the CTest ``TimeLimit`` setting
+in a :manual:`ctest(1)` :ref:`Dashboard Client` script,
+or on the :program:`ctest` command line via the :ctest-dashboard-option:`-D` option.
+
+The value is the maximum time, in seconds, allowed for the whole
+dashboard run, measured from the start of :program:`ctest`.
+The :command:`ctest_build` and :command:`ctest_coverage` commands do
+nothing if less than two minutes remain.  The :command:`ctest_test` and
+:command:`ctest_memcheck` commands limit the timeout of each test so
+that it ends at least two minutes before the time limit.