Merge topic 'doc-ctest-command-formatting'

695d6f62 Help: Revise ctest_* command documentation (#15559)
f8716c8b Help: Update cmake-generators(7) organization for GHS

1 files changed, 61 insertions, 24 deletions

diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst
index 5c0a4e9..e1b7793 100644
--- a/Help/command/ctest_build.rst
+++ b/Help/command/ctest_build.rst
@@ -1,36 +1,73 @@
 ctest_build
 -----------
 
-Build the project.
+Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
-              [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
+  ctest_build([BUILD <build-dir>] [APPEND]
+              [CONFIGURATION <config>]
+              [FLAGS <flags>]
+              [PROJECT_NAME <project-name>]
+              [TARGET <target-name>]
+              [NUMBER_ERRORS <num-err-var>]
+              [NUMBER_WARNINGS <num-warn-var>]
+              [RETURN_VALUE <result-var>]
+              )
 
-Builds the given build directory and stores results in Build.xml.  If no
-``BUILD`` is given, the :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+Build the project and store results in ``Build.xml``
+for submission with the :command:`ctest_submit` command.
 
-The ``TARGET`` variable can be used to specify a build target.  If none is
-specified, the default target ("ALL_BUILD" for Visual Studio generators and
-"all" in others) will be built.
+The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
+specify the build command line.  Otherwise the build command line is
+computed automatically based on the options given.
 
-The ``RETURN_VALUE`` option specifies a variable in which to store the
-return value of the native build tool.  The ``NUMBER_ERRORS`` and
-``NUMBER_WARNINGS`` options specify variables in which to store the number
-of build errors and warnings detected.
+The options are:
 
-The ``APPEND`` option marks results for append to those previously
-submitted to a dashboard server since the last :command:`ctest_start`.  Append
-semantics are defined by the dashboard server in use.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
-The ``QUIET`` option suppresses any CTest-specific non-error output
-that would have been printed to the console otherwise.  The summary
-of warnings / errors, as well as the output from the native build tool
-is unaffected by this option.
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
 
-If set, the contents of the variable ``CTEST_BUILD_COMMAND`` is used to build
-the project. In addition, if set, the contents of the variable
-``CTEST_BUILD_FLAGS`` are passed as additional arguments to the underlying
-build command. This can, e.g., be used to trigger a parallel build using the
-``-j`` option of make. See :module:`ProcessorCount` for an example.
+``CONFIGURATION <config>``
+  Specify the build configuration (e.g. ``Debug``).  If not
+  specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
+  Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
+  command will be used, if any.
+
+``FLAGS <flags>``
+  Pass additional arguments to the underlying build command.
+  If not specified the ``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.
+
+``PROJECT_NAME <project-name>``
+  Set the name of the project to build.  This should correspond
+  to the top-level call to the :command:`project` command.
+  If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
+
+``TARGET <target-name>``
+  Specify the name of a target to build.  If not specified the
+  ``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`).
+
+``NUMBER_ERRORS <num-err-var>``
+  Store the number of build errors detected in the given variable.
+
+``NUMBER_WARNINGS <num-warn-var>``
+  Store the number of build warnings detected in the given variable.
+
+``RETURN_VALUE <result-var>``
+  Store the return value of the native build tool in the given variable.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.  The summary of warnings / errors,
+  as well as the output from the native build tool is unaffected by
+  this option.