diff --git a/v2/doc/src/reference.xml b/v2/doc/src/reference.xml
index 9ea1df927..ae85f67ca 100644
--- a/v2/doc/src/reference.xml
+++ b/v2/doc/src/reference.xml
@@ -277,6 +277,19 @@ target1 debug gcc/runtime-link=dynamic,static
.
+
+ compile
+ compile-fail
+ link
+ link-fail
+ run
+ run-fail
+
+ Specialized rules for testing. See
+ .
+
+
+
obj
@@ -389,6 +402,13 @@ path-constant DATA : data/a.txt ;
+
+ test-suite
+
+ This rule is deprecated and equivalent to
+ alias.
+
+
diff --git a/v2/doc/src/tasks.xml b/v2/doc/src/tasks.xml
index 131ecdfbe..93ecbb41d 100644
--- a/v2/doc/src/tasks.xml
+++ b/v2/doc/src/tasks.xml
@@ -392,13 +392,71 @@ unit-test helpers_test
valgrind bin/$toolset/debug/helpers_test
-
+ There are few specialized testing rules, listed below:
+
+rule compile ( sources : requirements * : target-name ? )
+rule compile-fail ( sources : requirements * : target-name ? )
+rule link ( sources + : requirements * : target-name ? )
+rule link-fail ( sources + : requirements * : target-name ? )
+
+ They are are given a list of sources and requirements.
+ If the target name is not provided, the name of the first
+ source file is used instead. The compile*
+ tests try to compile the passed source. The link*
+ rules try to compile and link an application from all the passed sources.
+ The compile and link rules expect
+ that compilation/linking succeeds. The compile-fail
+ and link-fail rules, on the opposite, expect that
+ the compilation/linking fails.
+
+
+ There are two specialized rules for running applications, which
+ are more powerful than the unit-test rule. The
+ run rule has the following signature:
+
+rule run ( sources + : args * : input-files * : requirements * : target-name ?
+ : default-build * )
+
+ The rule builds application from the provided sources and runs it,
+ passing args and input-files
+ as command-line arguments. The args parameter
+ is passed verbatim and the values of the input-files
+ parameter are treated as paths relative to containing Jamfile, and are
+ adjusted if bjam is invoked from a different
+ directory. The run-fail rule is identical to the
+ run rule, except that it expects that the run fails.
+
+
+ All rules described in this section, if executed successfully,
+ create a special manifest file to indicate that the test passed.
+ For the unit-test rule the files is named
+ target-name.passed and
+ for the other rules it is called
+ target-name.test.
+ The run* rules also capture all output from the program,
+ and store it in a file named
+ target-name.output.
+
+ The run and the run-fail rules, if
+ the test passes, automatically delete the linked executable, to
+ save space. This behaviour can be suppressed by passing the
+ --preserve-test-targets command line option.
+
+ It is possible to print the list of all test targets (except for
+ unit-test) declared in your project, by passing
+ the --dump-tests command-line option. The output
+ will consist of lines of the form:
+
+boost-test(test-type) path : sources
+
+
+
+ It is possible to process the list of tests, the output of
+ bjam during command run, and the presense/absense of the
+ *.test files created when test passes into
+ human-readable status table of tests. Such processing utilities
+ are not included in Boost.Build.
- There are rules for more elaborate testing: compile,
- compile-fail, run and
- run-fail. They are more suitable for automated testing, and
- are not covered here.
-
diff --git a/v2/tools/testing.jam b/v2/tools/testing.jam
index 53911b564..25e590cf5 100644
--- a/v2/tools/testing.jam
+++ b/v2/tools/testing.jam
@@ -99,12 +99,12 @@ rule make-test ( target-type : sources + : requirements * : target-name ? )
return $(t) ;
}
-rule compile ( sources + : requirements * : target-name ? )
+rule compile ( sources : requirements * : target-name ? )
{
return [ make-test compile : $(sources) : $(requirements) : $(target-name) ] ;
}
-rule compile-fail ( sources + : requirements * : target-name ? )
+rule compile-fail ( sources : requirements * : target-name ? )
{
return [ make-test compile-fail : $(sources) : $(requirements) : $(target-name) ] ;
}
@@ -184,7 +184,10 @@ local rule get-library-name ( path )
else if $(match3) { return "" ; }
else if --dump-tests in [ modules.peek : ARGV ]
{
- EXIT Cannot extract library name from path $(path) ;
+ # The 'run' rule and others might be used outside
+ # boost. In that case, just return the path,
+ # since the 'library name' makes no sense.
+ return $(path) ;
}
}