mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-06 14:19:59 -05:00
Code Issues Packages Projects Releases Wiki Activity

FindCxxTest: Update documentation

Browse Source 
- Synced module documentation with other similar find modules.
- Extended example with imported target.
- Removed mentioning CMake 2.x in versionadded RST directives as these
  are now being cleaned in the CMake 4 documentation (CMake docs are at
  this point considering the 2.8.12.2 as the initial state upon which
  new and changed items are documented through versions - at least for
  modules).
- Added separate "Deprecated Variables" section.
- Changed the deprecation version number to 2.8.3 as it is for CMake
  version and not the module internal version 1.3.
- Added separate "Cache Variables" section.
- Used lowercase style for the cxxtest_add_test() command.
This commit is contained in:
Peter Kokot
2025-04-23 17:47:16 +02:00
parent 0a0f33dfad
commit 3a266612ec
1 changed files with 115 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Modules/FindCxxTest.cmake
+115 -75
View File
@@ -5,123 +5,163 @@
FindCxxTest FindCxxTest
----------- -----------
Find CxxTest unit testing framework. Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper
command to create test runners and integrate them with CTest.
Find the `CxxTest`_ suite and declare a helper macro for creating
unit tests and integrating them with CTest.
.. _`CxxTest`: https://github.com/CxxTest/cxxtest .. _`CxxTest`: https://github.com/CxxTest/cxxtest
Input Variables
^^^^^^^^^^^^^^^
``CXXTEST_USE_PYTHON``
.. deprecated:: 1.3
Only used in the case both Python & Perl
are detected on the system to control
which CxxTest code generator is used.
Valid only for CxxTest version 3.
In older versions of this Find Module,
this variable controlled if the Python test
generator was used instead of the Perl one,
regardless of which scripting language the
user had installed.
``CXXTEST_TESTGEN_ARGS``
.. versionadded:: 2.8.3
Specify a list of options to pass to the CxxTest code
generator. If not defined, ``--error-printer`` is passed.
Result Variables Result Variables
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
This module defines the following variables:
``CXXTEST_FOUND`` ``CXXTEST_FOUND``
True if the CxxTest framework was found Boolean indicating whether the CxxTest framework is found.
``CXXTEST_INCLUDE_DIRS`` ``CXXTEST_INCLUDE_DIRS``
Where to find the CxxTest include directory Include directories containing headers needed to use CxxTest.
``CXXTEST_PERL_TESTGEN_EXECUTABLE``
The perl-based test generator
``CXXTEST_PYTHON_TESTGEN_EXECUTABLE``
The python-based test generator
``CXXTEST_TESTGEN_EXECUTABLE`` ``CXXTEST_TESTGEN_EXECUTABLE``
.. versionadded:: 2.8.3 The path to the found CxxTest test generator script (Perl- or Python-based),
selected based on the found interpreter or user-specified preference.
The test generator that is actually used (chosen using user preferences
and interpreters found in the system)
``CXXTEST_TESTGEN_INTERPRETER`` ``CXXTEST_TESTGEN_INTERPRETER``
.. versionadded:: 2.8.3 The path to the found Perl or Python interpreter used to run the test
generator script, if needed (e.g., on platforms where script shebang lines are
not supported).
The full path to the Perl or Python executable on the system, on Cache Variables
platforms where the script cannot be executed using its shebang line.
Module Commands
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
The following cache variables may also be set:
``CXXTEST_PERL_TESTGEN_EXECUTABLE``
The path to the Perl-based CxxTest test generator script.
``CXXTEST_PYTHON_TESTGEN_EXECUTABLE``
The path to the Python-based CxxTest test generator script.
Hints
^^^^^
This module accepts the following variables before calling
``find_package(CxxTest)``:
``CXXTEST_TESTGEN_ARGS``
This variable can be set to specify a semicolon-separated list of command-line
options to pass to the CxxTest code generator. If not set, the default value
is ``--error-printer``.
Commands
^^^^^^^^
This module provides the following command if CxxTest is found:
.. command:: cxxtest_add_test .. command:: cxxtest_add_test
Create a CxxTest runner and adds it to the CTest testing suite: Creates a CxxTest runner and adds it to the CTest testing suite:
.. code-block:: cmake .. code-block:: cmake
CXXTEST_ADD_TEST(<test_name> <gen_source_file> cxxtest_add_test(<test-name> <gen-source-file> <input-files-to-testgen>...)
<input_files_to_testgen>...)
Parameters: Parameters:
``test_name`` ``<test-name>``
The name of the test The name of the test executable target to be created and registered as a
test in the CTest suite.
``gen_source_file`` ``<gen-source-file>``
The generated source filename to be generated by CxxTest The name of the source file to be generated by the CxxTest code generator.
This must be a relative path. It is interpreted relative to the
current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`).
``input_files_to_testgen`` ``<input-files-to-testgen>``
The list of header files containing the CxxTest::TestSuite's A list of header files containing test suite classes derived from the C++
to be included in this runner class ``CxxTest::TestSuite``, to be included in the test runner. These must
be given as absolute paths.
Example Usage Deprecated Variables
^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
The following example, if CxxTest is found, will: The following variables are deprecated and provided for backward compatibility:
* Invoke the testgen executable to autogenerate foo_test.cc in the ``CXXTEST_USE_PYTHON``
binary tree from "foo_test.h" in the current source directory. .. deprecated:: 2.8.3
* Create an executable and test called unittest_foo. In earlier versions of CMake, this hint variable was used to force the use
of the Python-based test generator instead of the Perl one, regardless of
which scripting language was installed. It is now only considered when both
Perl and Python interpreters are found.
A boolean hint variable that, when set to true, prefers the Python code
generator over the Perl one if both interpreters are found. This variable is
only relevant when using CxxTest version 3.
Examples
^^^^^^^^
The following example demonstrates how CxxTest can be used in CMake with this
module. If CxxTest is found:
* Additional interface :ref:`imported target <Imported Targets>` is created
manually in the project to encapsulate the CxxTest usage requirements and
link it to specified tests. Such target is useful, for example, when dealing
with multiple tests.
* Test generator is invoked to create ``foo_test.cc`` in the current binary
directory from the input header ``foo_test.h`` located in the current source
directory.
* An executable named ``unit_test_foo`` is built and registered as a test in
CTest.
.. code-block:: cmake .. code-block:: cmake
:caption: ``CMakeLists.txt``
find_package(CxxTest) find_package(CxxTest)
if(CXXTEST_FOUND)
include_directories(${CXXTEST_INCLUDE_DIR}) # Create interface imported target:
enable_testing() if(CXXTEST_FOUND AND NOT TARGET CxxTest::CxxTest)
CXXTEST_ADD_TEST(unittest_foo foo_test.cc add_library(CxxTest::CxxTest INTERFACE IMPORTED)
${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h) set_target_properties(
target_link_libraries(unittest_foo foo) # as needed CxxTest::CxxTest
PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CXXTEST_INCLUDE_DIRS}"
)
endif() endif()
``foo_test.h`` contains: # Add test:
if(CXXTEST_FOUND)
enable_testing()
cxxtest_add_test(
unit_test_foo
foo_test.cc
${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h
)
target_link_libraries(
unit_test_foo
PRIVATE
CxxTest::CxxTest
# Link any project targets as needed, if test depends on them:
foo
)
endif()
.. code-block:: c++ .. code-block:: c++
:caption: ``foo_test.h``
#include <cxxtest/TestSuite.h> #include <cxxtest/TestSuite.h>
class MyTestSuite : public CxxTest::TestSuite class MyTestSuite : public CxxTest::TestSuite
{ {
public: public:
void testAddition( void ) void testAddition(void)
{ {
TS_ASSERT( 1 + 1 > 1 ); TS_ASSERT(1 + 1 > 1);
TS_ASSERT_EQUALS( 1 + 1, 2 ); TS_ASSERT_EQUALS(1 + 1, 2);
} }
}; };
#]=======================================================================] #]=======================================================================]
# Version 1.4 (11/18/10) (CMake 2.8.4) # Version 1.4 (11/18/10) (CMake 2.8.4)
@@ -150,7 +190,7 @@ The following example, if CxxTest is found, will:
# Cleaned up and added more documentation # Cleaned up and added more documentation
#============================================================= #=============================================================
# CXXTEST_ADD_TEST (public macro) # cxxtest_add_test (public macro)
#============================================================= #=============================================================
macro(CXXTEST_ADD_TEST _cxxtest_testname _cxxtest_outfname) macro(CXXTEST_ADD_TEST _cxxtest_testname _cxxtest_outfname)
set(_cxxtest_real_outfname ${CMAKE_CURRENT_BINARY_DIR}/${_cxxtest_outfname}) set(_cxxtest_real_outfname ${CMAKE_CURRENT_BINARY_DIR}/${_cxxtest_outfname})