From c21f0eb30b775645974314efc3d53504fa786e97 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 22 Feb 2024 09:13:50 -0500 Subject: Help: Modernize create_test_sourcelist documentation --- Help/command/create_test_sourcelist.rst | 80 ++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 26 deletions(-) diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index 5f01a8b..83ce227 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst @@ -1,29 +1,57 @@ create_test_sourcelist ---------------------- -Create a test driver and source list for building test programs. - -.. code-block:: cmake - - create_test_sourcelist( - ... - [EXTRA_INCLUDE ] - [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( ... ...) + :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: + + ```` + 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 ``...`` sources + and the generated ```` source. + + ```` + 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 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
`` + Specify a header file to ``#include`` in the generated test driver source. + + ``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. -- cgit v0.12 From 2c646641ec99f8ec0caf993f2c5ac4178601e011 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 22 Feb 2024 09:15:47 -0500 Subject: Help: Document create_test_sourcelist source path convention Document the change in commit a29ca55b1f (create_test_sourcelist: use the full path to the driver, 2023-12-09, v3.29.0-rc1~264^2). --- Help/command/create_test_sourcelist.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index 83ce227..d0b43c4 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst @@ -19,6 +19,11 @@ large libraries to shrink the total required size. to build the test driver. The list will contain the ``...`` sources and the generated ```` source. + .. versionchanged:: 3.29 + + The test driver source is listed by absolute path in the build tree. + Previously it was listed only as ````. + ```` 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 -- cgit v0.12