Changes between Initial Version and Version 1 of CMakeTestRunFail

Timestamp:

Jun 12, 2007, 3:05:41 AM (15 years ago)

Author:

Douglas Gregor

Comment:

Initial documentation for boost_test_run_fail

CMakeTestRunFail

@@ +1 @@
+= CMake Macro Reference: `boost_test_run_fail` =
+The `boost_test_run_fail` macro creates a Boost regression test that will be built and executed. If
+the test can be built, executed, and exits with a return code that
+is not zero, it will be considered to have passed.
+
+{{{
+boost_test_run_fail(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_fail` creates an executable test `prg_exec_fail1`, linked against the static version of `boost_prg_exec_monitor`, which should return a non-zero exit code when run.
+
+{{{
+boost_test_run_fail(prg_exec_fail1 DEPENDS boost_prg_exec_monitor-static)
+}}}
+
+This example is from [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/libs/test/test/CMakeLists.txt libs/test/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).