echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Document CTest module BUILD_TESTING variable

Browse Source 
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)`.
This commit is contained in:
Robert Maynard 2024-10-22 09:54:07 -04:00 committed by Brad King
parent 6e6e688b80
commit 9510820d58
5 changed files with 42 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/add_test.rst
View File

@ -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)>`

10
Help/command/enable_testing.rst
View File

@ -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.

1
Help/manual/cmake-variables.7.rst
View File

@ -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

27
Help/variable/BUILD_TESTING.rst Normal file
View File

@ -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.

11
Modules/CTest.cmake
View File

@ -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