Merge topic 'patch-FindCxxTest'

3a266612ec FindCxxTest: Update documentation

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

Modules/FindCxxTest.cmake

@@ -5,123 +5,163 @@
 FindCxxTest
 -----------
 
-Find CxxTest unit testing framework.
-
-Find the `CxxTest`_ suite and declare a helper macro for creating
-unit tests and integrating them with CTest.
+Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper
+command to create test runners and integrate them with CTest.
 
 .. _`CxxTest`: https://github.com/CxxTest/cxxtest
 
-Input Variables
-^^^^^^^^^^^^^^^
-
-``CXXTEST_USE_PYTHON``
-  .. deprecated:: 1.3
+Result Variables
+^^^^^^^^^^^^^^^^
 
-  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.
+This module defines the following variables:
 
-  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_FOUND``
+  Boolean indicating whether the CxxTest framework is found.
 
-``CXXTEST_TESTGEN_ARGS``
-  .. versionadded:: 2.8.3
+``CXXTEST_INCLUDE_DIRS``
+  Include directories containing headers needed to use CxxTest.
 
-  Specify a list of options to pass to the CxxTest code
-  generator.  If not defined, ``--error-printer`` is passed.
+``CXXTEST_TESTGEN_EXECUTABLE``
+  The path to the found CxxTest test generator script (Perl- or Python-based),
+  selected based on the found interpreter or user-specified preference.
 
-Result Variables
-^^^^^^^^^^^^^^^^
+``CXXTEST_TESTGEN_INTERPRETER``
+  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).
 
-``CXXTEST_FOUND``
-  True if the CxxTest framework was found
+Cache Variables
+^^^^^^^^^^^^^^^
 
-``CXXTEST_INCLUDE_DIRS``
-  Where to find the CxxTest include directory
+The following cache variables may also be set:
 
 ``CXXTEST_PERL_TESTGEN_EXECUTABLE``
-  The perl-based test generator
+  The path to the Perl-based CxxTest test generator script.
 
 ``CXXTEST_PYTHON_TESTGEN_EXECUTABLE``
-  The python-based test generator
+  The path to the Python-based CxxTest test generator script.
 
-``CXXTEST_TESTGEN_EXECUTABLE``
-  .. versionadded:: 2.8.3
+Hints
+^^^^^
 
-  The test generator that is actually used (chosen using user preferences
-  and interpreters found in the system)
+This module accepts the following variables before calling
+``find_package(CxxTest)``:
 
-``CXXTEST_TESTGEN_INTERPRETER``
-  .. versionadded:: 2.8.3
+``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``.
 
-  The full path to the Perl or Python executable on the system, on
-  platforms where the script cannot be executed using its shebang line.
+Commands
+^^^^^^^^
 
-
-Module Commands
-^^^^^^^^^^^^^^^
+This module provides the following command if CxxTest is found:
 
 .. 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
 
-    CXXTEST_ADD_TEST(<test_name> <gen_source_file>
-                     <input_files_to_testgen>...)
+    cxxtest_add_test(<test-name> <gen-source-file> <input-files-to-testgen>...)
 
   Parameters:
 
-  ``test_name``
-    The name of the test
+  ``<test-name>``
+    The name of the test executable target to be created and registered as a
+    test in the CTest suite.
+
+  ``<gen-source-file>``
+    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>``
+    A list of header files containing test suite classes derived from the C++
+    class ``CxxTest::TestSuite``, to be included in the test runner.  These must
+    be given as absolute paths.
+
+Deprecated Variables
+^^^^^^^^^^^^^^^^^^^^
+
+The following variables are deprecated and provided for backward compatibility:
 
-  ``gen_source_file``
-    The generated source filename to be generated by CxxTest
+``CXXTEST_USE_PYTHON``
+  .. deprecated:: 2.8.3
+    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
+^^^^^^^^
 
-  ``input_files_to_testgen``
-    The list of header files containing the CxxTest::TestSuite's
-    to be included in this runner
+The following example demonstrates how CxxTest can be used in CMake with this
+module.  If CxxTest is found:
 
-Example Usage
-^^^^^^^^^^^^^
+* 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.
 
-The following example, if CxxTest is found, will:
+* 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.
 
-* 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.
+* An executable named ``unit_test_foo`` is built and registered as a test in
+  CTest.
 
 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``
 
   find_package(CxxTest)
+
+  # Create interface imported target:
+  if(CXXTEST_FOUND AND NOT TARGET CxxTest::CxxTest)
+    add_library(CxxTest::CxxTest INTERFACE IMPORTED)
+    set_target_properties(
+      CxxTest::CxxTest
+      PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CXXTEST_INCLUDE_DIRS}"
+    )
+  endif()
+
+  # Add test:
   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:
+    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++
+  :caption: ``foo_test.h``
 
   #include <cxxtest/TestSuite.h>
+
   class MyTestSuite : public CxxTest::TestSuite
   {
   public:
-     void testAddition( void )
-     {
-        TS_ASSERT( 1 + 1 > 1 );
-        TS_ASSERT_EQUALS( 1 + 1, 2 );
-     }
+    void testAddition(void)
+    {
+      TS_ASSERT(1 + 1 > 1);
+      TS_ASSERT_EQUALS(1 + 1, 2);
+    }
   };
-
 #]=======================================================================]
 
 # 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
 
 #=============================================================
-# CXXTEST_ADD_TEST (public macro)
+# cxxtest_add_test (public macro)
 #=============================================================
 macro(CXXTEST_ADD_TEST _cxxtest_testname _cxxtest_outfname)
     set(_cxxtest_real_outfname ${CMAKE_CURRENT_BINARY_DIR}/${_cxxtest_outfname})