Help: Document CTest module BUILD_TESTING variable

The `BUILD_TESTING` variable is referenced in `add_test` and
`enable_testing`.  It should be documented as it controls the
behavior tests working when projects use `include(CTest)`.

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

@@ -16,9 +16,14 @@ enable testing with CTest and dashboard submissions to CDash:
   ...
   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