| 1 | = CMake Macro Reference: `boost_test_run` = |
| 2 | |
| 3 | The `boost_test_run` macro creates a Boost regression test that will be build and executed. If |
| 4 | the test can be built, executed, and exits with a return code of |
| 5 | zero, it will be considered to have passed. |
| 6 | |
| 7 | {{{ |
| 8 | boost_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 |
| 18 | source files that will be built and linked into the test |
| 19 | executable. If no source files are provided, the file "testname.cpp" |
| 20 | will be used instead. |
| 21 | |
| 22 | There are several optional arguments to control how the regression |
| 23 | test 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 == |
| 54 | The 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 | {{{ |
| 57 | boost_test_run(signal_test DEPENDS boost_signals-static) |
| 58 | }}} |
| 59 | |
| 60 | This 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 == |
| 63 | This 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). |