Changes between Initial Version and Version 1 of CMakeTestRun


Ignore:
Timestamp:
Jun 12, 2007, 3:01:20 AM (15 years ago)
Author:
Douglas Gregor
Comment:

Initial documentation for boost_test_run

Legend:

Unmodified
Added
Removed
Modified
  • CMakeTestRun

    v1 v1  
     1= CMake Macro Reference: `boost_test_run` =
     2
     3The `boost_test_run` macro creates a Boost regression test that will be build and executed. If
     4the test can be built, executed, and exits with a return code of
     5zero, it will be considered to have passed.
     6
     7{{{
     8boost_test_run(testname
     9               [source1 source2 ...]
     10               [ARGS arg1 arg2... ]
     11               [COMPILE_FLAGS compileflags]
     12               [LINK_FLAGS linkflags]
     13               [LINK_LIBS linklibs]
     14               [DEPENDS libdepend1 libdepend2 ...])
     15}}}
     16
     17`testname` is the name of the test. `source1`, `source2`, etc. are the
     18source files that will be built and linked into the test
     19executable. If no source files are provided, the file "testname.cpp"
     20will be used instead.
     21
     22There are several optional arguments to control how the regression
     23test is built and executed:
     24
     25  ARGS::
     26    Provides additional arguments that will be passed to the
     27    test executable when it is run.
     28
     29  COMPILE_FLAGS::
     30    Provides additional compilation flags that will be
     31    used when building this test. For example, one might want to add
     32    "-DBOOST_SIGNALS_ASSERT=1" to turn on assertions within the library.
     33
     34  LINK_FLAGS::
     35    Provides additional flags that will be passed to the
     36    linker when linking the test excecutable. This option should not
     37    be used to link in additional libraries; see `LINK_LIBS` and
     38    `DEPENDS`.
     39
     40  LINK_LIBS::
     41    Provides additional libraries against which the test
     42    executable will be linked. For example, one might provide "expat"
     43    as options to `LINK_LIBS`, to state that this executable should be
     44    linked against the external "expat" library. Use `LINK_LIBS` for
     45    libraries external to Boost; for Boost libraries, use `DEPENDS`.
     46
     47  DEPENDS::
     48   States that this test executable depends on and links
     49    against another Boost library. The argument to `DEPENDS` should be
     50    the name of a particular variant of a Boost library, e.g.,
     51    `boost_signals-static`.
     52
     53== Example ==
     54The following invocation of `boost_test_run` creates an executable `signal_test`, which links against the static `boost_signals` library, and executes the test as part of regression testing.
     55
     56{{{
     57boost_test_run(signal_test DEPENDS boost_signals-static)
     58}}}
     59
     60This example is from [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/libs/signals/test/CMakeLists.txt libs/signals/test/CMakeLists.txt].
     61
     62== Where Defined ==
     63This macro is defined in the Boost Testing module in [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/tools/build/CMake/BoostTesting.cmake tools/build/CMake/BoostTesting.cmake]
     64
     65== TODO ==
     66
     67*  Improve handling of `DEPENDS`, so that we can specify just the
     68   library's abstract target (e.g., "boost_signals"), and possibly
     69   some features required for building the test (e.g.,
     70   `MULTI_THREADED, STATIC`). The test macros should then pick the
     71   best library variant available to meet those features and the
     72   current build variant (Debug or Release).