Re: [boost] Re: Documentation

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2004-06-13 12:51:56

David B. Held wrote:

> "David Abrahams" <dave_at_[hidden]> wrote in message
> news:ufz8zsm8j.fsf_at_boost-consulting.com...
> 
>>[...]
>>Doesn't this explain a bit?
>>
>>http://www.boost.org/more/getting_started.html#Results
> 
> 
> Well, it explains how the compiled libraries are named, which is
> exactly why I want to know the best way to link Boost.Test against
> a test program for another Boost library.  Since the library name
> contains the version number of Boost, I want to know if the Jamfile
> that builds *my* test should hardwire that version number into
> the name it looks for the library or not. 

Since you are talking about a Jamfile inside of the Boost tree, it 
should not have any version or platform or prefix reference in it. It 
should refer directly to the target in the Boost.Test library that you 
want to link to. The rest is determined automatically when the user 
builds the tests. Which in our case it means the regression test 
machines determine the build. -- See adjusted example below.

> Not only that, but how do
> I make Jam automatically look under the corresponding platform?
> It doesn't seem like a good idea to write the Jamfile for just one
> platform, or create a separate file for every platform.  

Definitely not a good idea ;-)

>Obviously,
> I haven't read up enough on Jam to know whether I can answer
> some of these questions myself.  

And assuming that the information was present in the first place. Which 
in this case it is but reading BBv1 docs is less than informative.

>But some of them seem like
> they probably don't have obvious answers anyway.  For instance,
> as a test writer, should I assume that the user who is building my
> test already built Boost.Test and installed it in the default location,
> or should I try to handle a case in which the user, say, installed
> the library in a system directory of some sort? 

Since they are going to be running it from the library sources, they are 
going to be building from within the Boost tree and when built will 
automatically build the correct test library. Of course that breaks if 
you are planning on distributing outside of the Boost tree.

> I don't see answers
> to these questions in any of the references pointed to, but maybe
> I'm just not looking closely enough.

It seems that there just are no simple to follow guidelines that answer 
those questions. And if I where to add some of that documentation, I'm 
not sure where it would go. There are at least 2 places where we 
describe regression test requirements/guidelines:

http://boost.org/more/regression.html#Adding_new_test
http://boost.org/more/test_policy.htm

> Just to be concrete, let me give an example of what I mean:
> 
> exe my_test
>         : <lib>libboost_test-gcc-1_31.a
>           my_test.cpp
>         : <include>$(BOOST_ROOT)
>     ;
> 
> I'm pretty sure this is not the ideal way to write the Jamfile, but
> at first blush, it seems the most obvious way, pending better
> answers to my questions.  I don't even know if that is the right
> syntax for linking to an external library or not.

OK, there are two ways of handling this depending on whether you are 
doing a test inside of the Boost tree or outside of it... When inside 
you can refer to the test library directly as such:

exe my_test
        : <lib>../../../libs/test/build/boost_test_exec_monitor
        my_test.cpp
        <include>$(BOOST_ROOT)
        ;

See boost-root/libs/format/test/Jamfile for such examples that also use 
the test system.

Or if you are outside of the Boost tree, but still have access to the 
Boost distribution, you can use the project relative targets:

* In your Jamrules add:

project boost : $(BOOST_ROOT) ;

* And then in the test do:

exe my_test
        : <lib>@boost./libs/test/build/boost_test_exec_monitor
        my_test.cpp
        <include>$(BOOST_ROOT)
        ;

See boost-root/libs/python/example for some uses of that.

As you can see neither refers to versions or compiler. That is 
determined when the user builds and is filled in automatically.

HTH.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq