Changes between Initial Version and Version 1 of CMakeTestRun

Timestamp:

Jun 12, 2007, 3:01:20 AM (15 years ago)

Author:

Douglas Gregor

Comment:

Initial documentation for boost_test_run

CMakeTestRun

@@ +1 @@
+= CMake Macro Reference: `boost_test_run` =
+
+The `boost_test_run` macro creates a Boost regression test that will be build and executed. If
+the test can be built, executed, and exits with a return code of
+zero, it will be considered to have passed.
+
+{{{
+boost_test_run(testname 
+               [source1 source2 ...]
+               [ARGS arg1 arg2... ]
+               [COMPILE_FLAGS compileflags]
+               [LINK_FLAGS linkflags]
+               [LINK_LIBS linklibs]
+               [DEPENDS libdepend1 libdepend2 ...])
+}}}
+
+`testname` is the name of the test. `source1`, `source2`, etc. are the
+source files that will be built and linked into the test
+executable. If no source files are provided, the file "testname.cpp"
+will be used instead.
+
+There are several optional arguments to control how the regression
+test is built and executed:
+
+  ARGS::
+    Provides additional arguments that will be passed to the
+    test executable when it is run.
+
+  COMPILE_FLAGS::
+    Provides additional compilation flags that will be
+    used when building this test. For example, one might want to add
+    "-DBOOST_SIGNALS_ASSERT=1" to turn on assertions within the library.
+
+  LINK_FLAGS::
+    Provides additional flags that will be passed to the
+    linker when linking the test excecutable. This option should not
+    be used to link in additional libraries; see `LINK_LIBS` and
+    `DEPENDS`.
+
+  LINK_LIBS::
+    Provides additional libraries against which the test
+    executable will be linked. For example, one might provide "expat"
+    as options to `LINK_LIBS`, to state that this executable should be
+    linked against the external "expat" library. Use `LINK_LIBS` for
+    libraries external to Boost; for Boost libraries, use `DEPENDS`.
+
+  DEPENDS:: 
+   States that this test executable depends on and links
+    against another Boost library. The argument to `DEPENDS` should be
+    the name of a particular variant of a Boost library, e.g.,
+    `boost_signals-static`.
+
+== Example ==
+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.
+
+{{{
+boost_test_run(signal_test DEPENDS boost_signals-static)
+}}}
+
+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].
+
+== Where Defined ==
+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]
+
+== TODO ==
+
+*  Improve handling of `DEPENDS`, so that we can specify just the
+   library's abstract target (e.g., "boost_signals"), and possibly
+   some features required for building the test (e.g.,
+   `MULTI_THREADED, STATIC`). The test macros should then pick the
+   best library variant available to meet those features and the
+   current build variant (Debug or Release).