Merge topic 'doc-BUILD_TESTING'

9510820d58 Help: Document CTest module BUILD_TESTING variable
6e6e688b80 CTest: Improve formatting of documentation cmake code blocks

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9927

Help/command/add_test.rst

@@ -16,7 +16,7 @@ if necessary.  See policy :policy:`CMP0110`.
 
 CMake only generates tests if the :command:`enable_testing` command has been
 invoked.  The :module:`CTest` module invokes ``enable_testing`` automatically
-unless ``BUILD_TESTING`` is set to ``OFF``.
+unless :variable:`BUILD_TESTING` is set to ``OFF``.
 
 Tests added with the ``add_test(NAME)`` signature support using
 :manual:`generator expressions <cmake-generator-expressions(7)>`

Help/command/enable_testing.rst

@@ -9,12 +9,12 @@ Enable testing for current directory and below.
 
 Enables testing for this directory and below.
 
-This command should be in the source directory root
-because ctest expects to find a test file in the build
-directory root.
+This command should be in the top-level source directory because
+:manual:`ctest(1)` expects to find a test file in the top-level
+build directory.
 
 This command is automatically invoked when the :module:`CTest`
-module is included, except if the ``BUILD_TESTING`` option is
-turned off.
+module is included, except if the :variable:`BUILD_TESTING`
+option is turned off.
 
 See also the :command:`add_test` command.

Help/manual/cmake-variables.7.rst

@@ -175,6 +175,7 @@ Variables that Change Behavior
    :maxdepth: 1
 
    /variable/BUILD_SHARED_LIBS
+   /variable/BUILD_TESTING
    /variable/CMAKE_ABSOLUTE_DESTINATION_FILES
    /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
    /variable/CMAKE_APPBUNDLE_PATH

Help/variable/BUILD_TESTING.rst

@@ -0,0 +1,27 @@
+BUILD_TESTING
+-------------
+
+Control whether the :module:`CTest` module invokes :command:`enable_testing`.
+
+The :module:`CTest` module, when loaded by ``include(CTest)``,
+runs code of the form:
+
+.. code-block:: cmake
+
+  option(BUILD_TESTING "..." ON)
+  if (BUILD_TESTING)
+     # ...
+     enable_testing()
+     # ...
+  endif()
+
+This creates a ``BUILD_TESTING`` option that controls whether the
+:command:`enable_testing` command is invoked to enable generation
+of tests to run using :manual:`ctest(1)`.  See the :command:`add_test`
+command to create tests.
+
+.. note::
+
+  Call ``include(CTest)`` in the top-level source directory since
+  :manual:`ctest(1)` expects to find a test file in the top-level
+  build directory.

Modules/CTest.cmake

@@ -8,15 +8,24 @@ CTest
 Configure a project for testing with CTest/CDash
 
 Include this module in the top CMakeLists.txt file of a project to
-enable testing with CTest and dashboard submissions to CDash::
+enable testing with CTest and dashboard submissions to CDash:
+
+.. code-block:: cmake
 
   project(MyProject)
   ...
   include(CTest)
 
-The module automatically creates a ``BUILD_TESTING`` option that selects
-whether to enable testing support (``ON`` by default).  After including
-the module, use code like::
+The module automatically creates the following variables:
+
+:variable:`BUILD_TESTING`
+
+  Option selecting whether ``include(CTest)`` calls :command:`enable_testing`.
+  The option is ``ON`` by default when created by the module.
+
+After including the module, use code like:
+
+.. code-block:: cmake
 
   if(BUILD_TESTING)
     # ... CMake code to create tests ...
@@ -25,7 +34,9 @@ the module, use code like::
 to creating tests when testing is enabled.
 
 To enable submissions to a CDash server, create a ``CTestConfig.cmake``
-file at the top of the project with content such as::
+file at the top of the project with content such as:
+
+.. code-block:: cmake
 
   set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
   set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
@@ -40,7 +51,9 @@ build output for errors and warnings and reports them with surrounding
 context from the build log.  This generic approach works for all build
 tools, but does not give details about the command invocation that
 produced a given problem.  One may get more detailed reports by setting
-the :variable:`CTEST_USE_LAUNCHERS` variable::
+the :variable:`CTEST_USE_LAUNCHERS` variable:
+
+.. code-block:: cmake
 
   set(CTEST_USE_LAUNCHERS 1)