Merge branch 'add_ctest_progress_docs' into release-3.13

Merge-request: !2454

3 files changed, 32 insertions, 4 deletions

diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst
new file mode 100644
index 0000000..a8e15bc
--- /dev/null
+++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst
@@ -0,0 +1,14 @@
+CTEST_PROGRESS_OUTPUT
+---------------------
+
+Boolean environment variable that affects how :manual:`ctest <ctest(1)>`
+command output reports overall progress.  When set to 1, TRUE, ON or anything
+else that evaluates to boolean true, progress is reported by repeatedly
+updating the same line.  This greatly reduces the overall verbosity, but is
+only supported when output is sent directly to a terminal.  If the environment
+variable is not set or has a value that evaluates to false, output is reported
+normally with each test having its own start and end lines logged to the
+output.
+
+The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this
+environment variable if both are given.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 42aeabc..31aa723 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -53,5 +53,6 @@ Environment Variables for CTest
    /envvar/CTEST_INTERACTIVE_DEBUG_MODE
    /envvar/CTEST_OUTPUT_ON_FAILURE
    /envvar/CTEST_PARALLEL_LEVEL
+   /envvar/CTEST_PROGRESS_OUTPUT
    /envvar/CTEST_USE_LAUNCHERS_DEFAULT
    /envvar/DASHBOARD_TEST_FROM_CTEST
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 9553d15..e24b10d 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -35,6 +35,19 @@ Options
  which one should be tested.  Example configurations are "Debug" and
  "Release".
 
+``--progress``
+ Enable short progress output from tests.
+
+ When the output of ``ctest`` is being sent directly to a terminal, the
+ progress through the set of tests is reported by updating the same line
+ rather than printing start and end messages for each test on new lines.
+ This can significantly reduce the verbosity of the test output.
+ Test completion messages are still output on their own line for failed
+ tests and the final test summary will also still be logged.
+
+ This option can also be enabled by setting the environment variable
+ :envvar:`CTEST_PROGRESS_OUTPUT`.
+
 ``-V,--verbose``
  Enable verbose output from tests.
 
@@ -55,8 +68,8 @@ Options
 
 ``--output-on-failure``
  Output anything outputted by the test program if the test should fail.
- This option can also be enabled by setting the environment variable
- ``CTEST_OUTPUT_ON_FAILURE``.
+ This option can also be enabled by setting the
+ :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
 
 ``-F``
  Enable failover.
@@ -70,7 +83,7 @@ Options
 
  This option tells CTest to run the tests in parallel using given
  number of jobs. This option can also be set by setting the
- environment variable ``CTEST_PARALLEL_LEVEL``.
+ :envvar:`CTEST_PARALLEL_LEVEL` environment variable.
 
  This option can be used with the :prop_test:`PROCESSORS` test property.
 
@@ -867,7 +880,7 @@ Configuration settings include:
 
   * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE`
   * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``,
-    initialized by the ``CMAKE_CONFIG_TYPE`` environment variable
+    initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable
 
 ``LabelsForSubprojects``
   Specify a semicolon-separated list of labels that will be treated as