mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-09 15:20:56 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'doc-create_test_sourcelist' into release-3.29

Browse Source 
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
This commit is contained in:
Brad King
2024-02-23 12:41:10 +00:00
committed by Kitware Robot
parent dc45b20aca 2c646641ec
commit 9cd34156f4
1 changed files with 56 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
Help/command/create_test_sourcelist.rst
View File

@@ -1,29 +1,62 @@
create_test_sourcelist
----------------------
Create a test driver and source list for building test programs.
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.
.. code-block:: cmake
.. signature::
create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...)
:target: original
create_test_sourcelist(<sourceListName> <driverName>
<tests> ...
[EXTRA_INCLUDE <include>]
[FUNCTION <function>])
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.
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.
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.