diff options
| author | Brad King <brad.king@kitware.com> | 2024-02-23 12:41:10 (GMT) |
|---|---|---|
| committer | Kitware Robot <kwrobot@kitware.com> | 2024-02-23 12:41:28 (GMT) |
| commit | 5bfb961c64f73d7f3377dea7e08fff201c3a8c52 (patch) | |
| tree | 1371c338c909445d6b6ea545737a8e74c1f2b76f /Help | |
| parent | 87f270800cb675f0e1e4e3a6419a8f5b79afdae4 (diff) | |
| parent | 2c646641ec99f8ec0caf993f2c5ac4178601e011 (diff) | |
| download | CMake-5bfb961c64f73d7f3377dea7e08fff201c3a8c52.zip CMake-5bfb961c64f73d7f3377dea7e08fff201c3a8c52.tar.gz CMake-5bfb961c64f73d7f3377dea7e08fff201c3a8c52.tar.bz2 | |
Merge topic 'doc-create_test_sourcelist'
2c646641ec Help: Document create_test_sourcelist source path convention
c21f0eb30b Help: Modernize create_test_sourcelist documentation
Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !9281
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/create_test_sourcelist.rst | 85 |
1 files changed, 59 insertions, 26 deletions
diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index 5f01a8b..d0b43c4 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst @@ -1,29 +1,62 @@ create_test_sourcelist ---------------------- -Create a test driver and source list for building test programs. - -.. code-block:: cmake - - create_test_sourcelist(<sourceListName> <driverName> - <tests> ... - [EXTRA_INCLUDE <include>] - [FUNCTION <function>]) - -A test driver is a program that links together many small tests into a single -executable. This is useful when building static executables with large -libraries to shrink the total required size. The list of source files needed -to build the test driver will be in ``sourceListName``. ``driverName`` is the -name of the test driver program. The rest of the arguments consist of a list -of test source files and can be semicolon separated. Each test source file -should have a function in it that is the same name as the file with no -extension (``foo.cxx`` should have ``int foo(int, char*[]);``). ``driverName`` -will be able to call each of the tests by name on the command line. If -``EXTRA_INCLUDE`` is specified, then the next argument is included into the -generated file. If ``FUNCTION`` is specified, then the next argument is taken -as a function name that is passed pointers to ``argc`` and ``argv``. This can -be used to add extra command line processing to each test. The -``CMAKE_TESTDRIVER_BEFORE_TESTMAIN`` cmake variable can be set to have code -that will be placed directly before calling the test ``main`` function. -``CMAKE_TESTDRIVER_AFTER_TESTMAIN`` can be set to have code that will be -placed directly after the call to the test ``main`` function. +Create a test driver program that links together many small tests into a +single executable. This is useful when building static executables with +large libraries to shrink the total required size. + +.. signature:: + create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...) + :target: original + + Generate a test driver source file from a list of individual test sources + and provide a combined list of sources that can be built as an executable. + + The options are: + + ``<sourceListName>`` + The name of a variable in which to store the list of source files needed + to build the test driver. The list will contain the ``<test>...`` sources + and the generated ``<driverName>`` source. + + .. versionchanged:: 3.29 + + The test driver source is listed by absolute path in the build tree. + Previously it was listed only as ``<driverName>``. + + ``<driverName>`` + Name of the test driver source file to be generated into the build tree. + The source file will contain a ``main()`` program entry point that + dispatches to whatever test is named on the command line. + + ``<test>...`` + Test source files to be added to the driver binary. Each test source + file must have a function in it that is the same name as the file with the + extension removed. For example, a ``foo.cxx`` test source might contain: + + .. code-block:: c++ + + int foo(int argc, char** argv) + + ``EXTRA_INCLUDE <header>`` + Specify a header file to ``#include`` in the generated test driver source. + + ``FUNCTION <function>`` + Specify a function to be called with pointers to ``argc`` and ``argv``. + The function may be provided in the ``EXTRA_INCLUDE`` header: + + .. code-block:: c++ + + void function(int* pargc, char*** pargv) + + This can be used to add extra command line processing to each test. + +Additionally, some CMake variables affect test driver generation: + +.. variable:: CMAKE_TESTDRIVER_BEFORE_TESTMAIN + + Code to be placed directly before calling each test's function. + +.. variable:: CMAKE_TESTDRIVER_AFTER_TESTMAIN + + Code to be placed directly after the call to each test's function. |