diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index f16142e7b..b5c7a179e 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -14,3 +14,9 @@ CTEST_SOURCE_DIRECTORY and CTEST_BINARY_DIRECTORY. If the track is specified, the submissions will go to the specified track. If APPEND is used, the existing TAG is used rather than creating a new one based on the current time stamp. + +If the ``CTEST_CHECKOUT_COMMAND`` variable (or the ``CTEST_CVS_CHECKOUT`` +variable) is set, its content is treated as command-line. The command is +invoked with the current working directory set to the parent of the source +directory, even if the source directory already exists. This can be used +to create the source tree from a version control repository. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 17c3236b5..8ff73a460 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -128,6 +128,8 @@ versions of CMake. Do not use them in new code. /command/variable_requires /command/write_file +.. _`CTest Commands`: + CTest Commands ============== diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 60d08dd13..6fb4e82ff 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -365,6 +365,607 @@ Options .. include:: OPTIONS_HELP.txt +Dashboard Client +================ + +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. + +.. _`CDash`: http://cdash.org/ + +Dashboard Client Steps +---------------------- + +CTest defines an ordered list of testing steps of which some or all may +be run as a dashboard client: + +``Start`` + Start a new dashboard submission to be composed of results recorded + by the following steps. + See the `CTest Start Step`_ section below. + +``Update`` + Update the source tree from its version control repository. + Record the old and new versions and the list of updated source files. + See the `CTest Update Step`_ section below. + +``Configure`` + Configure the software by running a command in the build tree. + Record the configuration output log. + See the `CTest Configure Step`_ section below. + +``Build`` + Build the software by running a command in the build tree. + Record the build output log and detect warnings and errors. + See the `CTest Build Step`_ section below. + +``Test`` + Test the software by loading a ``CTestTestfile.cmake`` + from the build tree and executing the defined tests. + Record the output and result of each test. + See the `CTest Test Step`_ section below. + +``Coverage`` + Compute coverage of the source code by running a coverage + analysis tool and recording its output. + See the `CTest Coverage Step`_ section below. + +``MemCheck`` + Run the software test suite through a memory check tool. + Record the test output, results, and issues reported by the tool. + See the `CTest MemCheck Step`_ section below. + +``Submit`` + Submit results recorded from other testing steps to the + software quality dashboard server. + See the `CTest Submit Step`_ section below. + +Dashboard Client Modes +---------------------- + +CTest defines three modes of operation as a dashboard client: + +``Nightly`` + This mode is intended to be invoked once per day, typically at night. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default. Selected steps run even + if the ``Update`` step reports no changes to the source tree. + +``Continuous`` + This mode is intended to be invoked repeatedly throughout the day. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default, but exits after the + ``Update`` step if it reports no changes to the source tree. + +``Experimental`` + This mode is intended to be invoked by a developer to test local changes. + It enables the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``, + and ``Submit`` steps by default. + +Dashboard Client via CTest Command-Line +--------------------------------------- + +CTest can perform testing on an already-generated build tree. +Run the ``ctest`` command with the current working directory set +to the build tree and use one of these signatures:: + + ctest -D [] + ctest -M [ -T ]... + +The ```` must be one of the above `Dashboard Client Modes`_, +and each ```` must be one of the above `Dashboard Client Steps`_. + +CTest reads the `Dashboard Client Configuration`_ settings from +a file in the build tree called either ``CTestConfiguration.ini`` +or ``DartConfiguration.tcl`` (the names are historical). The format +of the file is:: + + # Lines starting in '#' are comments. + # Other non-blank lines are key-value pairs. + : + +where ```` is the setting name and ```` is the +setting value. + +In build trees generated by CMake, this configuration file is +generated by the :module:`CTest` module if included by the project. +The module uses variables to obtain a value for each setting +as documented with the settings below. + +.. _`CTest Script`: + +Dashboard Client via CTest Script +--------------------------------- + +CTest can perform testing driven by a :manual:`cmake-language(7)` +script that creates and maintains the source and build tree as +well as performing the testing steps. Run the ``ctest`` command +with the current working directory set outside of any build tree +and use one of these signatures:: + + ctest -S