= 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/branches/CMake/Boost_1_35_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/branches/CMake/Boost_1_35_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).