From 676d1da38b740c7836721b37b9686a0ca6a3ca9c Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 23 Jun 2023 09:24:23 -0400 Subject: [PATCH] FindCxxTest: Modernize documentation formatting --- Modules/FindCxxTest.cmake | 194 +++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 106 deletions(-) diff --git a/Modules/FindCxxTest.cmake b/Modules/FindCxxTest.cmake index a58c4c29c7..714927fdc0 100644 --- a/Modules/FindCxxTest.cmake +++ b/Modules/FindCxxTest.cmake @@ -12,132 +12,114 @@ unit tests and integrating them with CTest. .. _`CxxTest`: https://github.com/CxxTest/cxxtest#readme -INPUT Variables +Input Variables +^^^^^^^^^^^^^^^ -:: +``CXXTEST_USE_PYTHON`` + .. deprecated:: 1.3 - CXXTEST_USE_PYTHON [deprecated since 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. + 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 +^^^^^^^^^^^^^^^^ + +``CXXTEST_FOUND`` + True if the CxxTest framework was found + +``CXXTEST_INCLUDE_DIRS`` + Where to find the CxxTest include directory + +``CXXTEST_PERL_TESTGEN_EXECUTABLE`` + The perl-based test generator + +``CXXTEST_PYTHON_TESTGEN_EXECUTABLE`` + The python-based test generator + +``CXXTEST_TESTGEN_EXECUTABLE`` + .. versionadded:: 2.8.3 + + The test generator that is actually used (chosen using user preferences + and interpreters found in the system) + +``CXXTEST_TESTGEN_INTERPRETER`` + .. versionadded:: 2.8.3 + + The full path to the Perl or Python executable on the system, on + platforms where the script cannot be executed using its shebang line. +Module Commands +^^^^^^^^^^^^^^^ -:: +.. command:: cxxtest_add_test - NOTE: 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. + Create a CxxTest runner and adds it to the CTest testing suite:: + CXXTEST_ADD_TEST( + ...) + Parameters: -:: + ``test_name`` + The name of the test - CXXTEST_TESTGEN_ARGS (since CMake 2.8.3) - Specify a list of options to pass to the CxxTest code - generator. If not defined, --error-printer is - passed. + ``gen_source_file`` + The generated source filename to be generated by CxxTest + ``input_files_to_testgen`` + The list of header files containing the CxxTest::TestSuite's + to be included in this runner +Example Usage +^^^^^^^^^^^^^ -OUTPUT Variables +The following example, if CxxTest is found, will: -:: +* Invoke the testgen executable to autogenerate foo_test.cc in the + binary tree from "foo_test.h" in the current source directory. +* Create an executable and test called unittest_foo. - CXXTEST_FOUND - True if the CxxTest framework was found - CXXTEST_INCLUDE_DIRS - Where to find the CxxTest include directory - CXXTEST_PERL_TESTGEN_EXECUTABLE - The perl-based test generator - CXXTEST_PYTHON_TESTGEN_EXECUTABLE - The python-based test generator - CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3) - The test generator that is actually used (chosen using user preferences - and interpreters found in the system) - CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3) - The full path to the Perl or Python executable on the system, on - platforms where the script cannot be executed using its shebang line. +.. code-block:: cmake + find_package(CxxTest) + if(CXXTEST_FOUND) + include_directories(${CXXTEST_INCLUDE_DIR}) + enable_testing() + CXXTEST_ADD_TEST(unittest_foo foo_test.cc + ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h) + target_link_libraries(unittest_foo foo) # as needed + endif() +``foo_test.h`` contains: -MACROS for optional use by CMake users: +.. code-block:: c++ -:: + #include + class MyTestSuite : public CxxTest::TestSuite + { + public: + void testAddition( void ) + { + TS_ASSERT( 1 + 1 > 1 ); + TS_ASSERT_EQUALS( 1 + 1, 2 ); + } + }; - CXXTEST_ADD_TEST( ) - Creates a CxxTest runner and adds it to the CTest testing suite - Parameters: - test_name The name of the test - gen_source_file The generated source filename to be - generated by CxxTest - input_files_to_testgen The list of header files containing the - CxxTest::TestSuite's to be included in - this runner - - - -:: - - #============== - Example Usage: - - - -:: - - find_package(CxxTest) - if(CXXTEST_FOUND) - include_directories(${CXXTEST_INCLUDE_DIR}) - enable_testing() - - - -:: - - CXXTEST_ADD_TEST(unittest_foo foo_test.cc - ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h) - target_link_libraries(unittest_foo foo) # as needed - endif() - - - -:: - - This will (if CxxTest is found): - 1. Invoke the testgen executable to autogenerate foo_test.cc in the - binary tree from "foo_test.h" in the current source directory. - 2. Create an executable and test called unittest_foo. - - - -:: - - #============= - Example foo_test.h: - - - -:: - - #include - - - -:: - - class MyTestSuite : public CxxTest::TestSuite - { - public: - void testAddition( void ) - { - TS_ASSERT( 1 + 1 > 1 ); - TS_ASSERT_EQUALS( 1 + 1, 2 ); - } - }; #]=======================================================================] # Version 1.4 (11/18/10) (CMake 2.8.4)