Re: [Boost-build] testing rules docs

From: Vladimir Prus (ghost_at_[hidden])
Date: 2007-02-02 02:10:22

On Sunday 07 January 2007 07:42, Peter wrote:

[cc for convenient, please reply to list]

> Could you please let me know where in the source tree the testing.html file
> is?  I would like to update some parts of it and submit it.

Peter,

testing.html is not present itself in CVS, it is generated from
tools/build/v2/doc/src/tasks.xml

and the generation instructions can be found at:

        http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/quickbook.html

> I have tried searching through the tools/build directory but have not had
> much luck.
> 
> Some questions on the document:
> 
> 1.	Your testing page states that the simplest way to implement
> unit-test's is with the "unit-test" rule.  Yet when I look in the
> testing.jam file I see:
> 
> (Lines 23 and 24)
> #  For historical reason, a 'unit-test' rule is available which
> #  has the same syntax as 'exe' and behaves just like 'run'.
> 
> (Note:  that the above lines get printed out when you do bjam --help
> testing)
> 
> Further down (lines 257 to 261) I see that it states that the unit-test rule
> was left in because it is more user-friendly.  This was because of this post
> to the mail list: http://tinyurl.com/yxhrqd
> 
> It might be worthwhile to state the pro's and con's between the "unit-test"
> and the run rule.

You're right. Basically, most "ordinary" projects would use 'unit-test' -- it's just like
exe, but with automatic run functionality. 

The 'run' rule actually is a bit more complete and more complex mechanism
-- you can pass arguments and files to the run program, and it captures the output.

So 'run' rule is to be used only when  you really need the extra functionality.

> 2.	I am probably doing something wrong but I could not work out how to
> get the run rule to work.  You have provided an example for the "unit-test"
> rule but not one for the "run" rule.
> 
> As I have stated I have been looking through some of the regression tests
> and noticed that its usage is something like:
> 
> test-suite test_name
> 	:
> 	[ run mytest.cpp
> 		:
> 		:
> 		: # requirements
> 			<include>$(BOOST_ROOT)
> <library-path>$(BOOST_ROOT)/lib
> 	]
> 	;
> 
> Is this the correct usage?  Or is there another way you can call the "run"
> rule?

This looks like correct usage. What kind of problem do you get?

> 3.	I am guessing there is probably a historical reason why this is the
> case but why is the format of the "run" rule different to all the other test
> rules (eg "compile", "compile-fail", "link" and "link-fail")?
> 
> The format of run is:
> 
> rule run ( sources + : args * : input-files * : requirements * : target-name
> ? : default-build * )
> 
> The format for the others is:
> 
> rule compile ( sources : requirements * : target-name ? )
> 
> This is non-intuitive I was expecting to be able to swap from compile to run
> while I was testing what they could do.
> 
> Also if you look here: http://tinyurl.com/skhpq it seems to suggest that
> this is the commonly expected syntax.
> 
> I am guessing it is to late to change it but would it be possible to change
> the "run" rule to something like:
> 
> rule run ( sources + : requirements * : target-name : args * : input-files *
> ? : default-build * )

The reason 'run' is different is historical. And indeed it might be too much work
to adjust all of Boost to any different syntax.

> 4.	This is more a minor thing and is probably expected knowledge for
> using bjam but what exactly does the "helpers" (last word prior to the
> semi-colon) mean in this line:
> 
> unit-test helpers_test : helpers_test.cpp helpers ;
> 
> Is it another source file or executable?

Oops. Yes, 'helpers' is supposed to be a name of another target, like:

        lib helpers : helpers.cpp ;

- Volodya