diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 5c0a4e991..e1b7793fc 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 ] [APPEND] + [CONFIGURATION ] + [FLAGS ] + [PROJECT_NAME ] + [TARGET ] + [NUMBER_ERRORS ] + [NUMBER_WARNINGS ] + [RETURN_VALUE ] + ) -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 `` + 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 `` + Specify the build configuration (e.g. ``Debug``). If not + specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked. + Otherwise the ``-C `` option given to the :manual:`ctest(1)` + command will be used, if any. + +``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 `` + 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 `` + 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 `` + Store the number of build errors detected in the given variable. + +``NUMBER_WARNINGS `` + Store the number of build warnings detected in the given variable. + +``RETURN_VALUE `` + 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. diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 61d93209c..851c29292 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -1,25 +1,39 @@ ctest_configure --------------- -Configure the project build tree. +Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. :: - ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND] - [OPTIONS options] [RETURN_VALUE res] [QUIET]) + ctest_configure([BUILD ] [SOURCE ] [APPEND] + [OPTIONS ] [RETURN_VALUE ] [QUIET]) -Configures the given build directory and stores results in -Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY -variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY -variable is used. The OPTIONS argument specifies command line -arguments to pass to the configuration tool. The RETURN_VALUE option -specifies a variable in which to store the return value of the native -build tool. +Configure the project build tree and record results in ``Configure.xml`` +for submission with the :command:`ctest_submit` command. -The APPEND option marks results for append to those previously -submitted to a dashboard server since the last ctest_start. Append -semantics are defined by the dashboard server in use. +The options are: -The QUIET option suppresses any CTest-specific non-error messages -that would have otherwise been printed to the console. Output from -the underlying configure command is not affected. +``BUILD `` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``SOURCE `` + Specify the source directory. If not given, the + :variable:`CTEST_SOURCE_DIRECTORY` variable is used. + +``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. + +``OPTIONS `` + Specify command-line arguments to pass to the configuration tool. + +``RETURN_VALUE `` + Store in the ```` variable the return value of the native + configuration tool. + +``QUIET`` + Suppress any CTest-specific non-error messages that would have + otherwise been printed to the console. Output from the underlying + configure command is not affected. diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index bac5c1c9a..12429b99d 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -1,25 +1,39 @@ ctest_coverage -------------- -Collect coverage tool results. +Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. :: - ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND] - [LABELS label1 [label2 [...]]]) + ctest_coverage([BUILD ] [APPEND] + [LABELS