Re: [boost] How to specify Boost headers location properly

Subject: Re: [boost] How to specify Boost headers location properly
From: Vladimir Prus (ghost_at_[hidden])
Date: 2010-03-10 17:01:25

Mateusz Loskot wrote:
> Hi,
> 
> I'm trying to learn what is, let's say, canonical form of
> configuring Boost headers location in Jamfiles of test and
> example programs for:
> 
> 1) Libraries that live inside Boost tree (SVN trunk) - Boost libraries.
> 
> 2) Libraries that are close-to-Boost, it is Sandbox, libraries
> being reviewed and libraries already reviewed and accepted
> but not yet included in Boost tree
> 
> In the case 1), I assume it's required that a library is configured to
> use headers from the same Boost tree where it is actually included.
> 
> In the case 2), I assume that it's recommended to configure a library in
> such way that allows compilation in two ways:
> a) user copies library to Boost tree and compiles, i.e. examples, by
> executing bjam inside BOOST_ROOT/libs/LIBRARY/example
> 
> b) user does not copy library to Boost tree, but keeps it externally
> and still can do:
> cd BOOST_ROOT/libs/LIBRARY/example
> bjam
> 
> 
> I was explained by folks on #boost channel, that there is
> no requirement for user to:
> - set environment variables like BOOST_ROOT
> - or to set global <include> requirements in user-config.jam, like this:
> 
> project : requirements <include>/path/to/boost/root ;
> 
> As I was told, the only entry in user-config.jam related to location of
> Boost headers should be
> 
> use-project boost : /path/to/boost/root ;
> 
> I'm looking at various Jamfiles in trunk and sandbox and I'm a bit confused.
> 
> For 1st example for the case 1),
> in trunk/libs/accumulators/example/Jamfile.v2, Boost headers are
> located by relative path and mysterious $(BOOST_ROOT)
> 
> exe example
>     :
>         main.cpp
>     :
>         <include>../../..
>         <include>$(BOOST_ROOT)
>     ;
> 
> 
> For 2nd example of the case 1),
> in libs/program_options/example/Jamfile.v2, there is no <include>
> or <source> requirement configured, so AFAIU, it means global
> Boost Jamroot takes care of setting headers location.

Yes, that's correct. Boost's Jamroot has

        <include>.

in requirements, which means that no Jamfile inside boost has to
specify either <include>../../.. or <include>$BOOST_ROOT.

> For 1st example for the case 2), it is ITL library that was submitted to
> review, not yet in Boost tree, I see similar double-include trick in
> Jamfile of examples:
> 
> https://svn.boost.org/svn/boost/sandbox/itl/libs/itl/example/Jamfile.v2
> 
> exe overlap_counter
>     :
>         overlap_counter_/overlap_counter.cpp
>     :
>         <include>../../..
>         <include>$(BOOST_ROOT)
>     ;
> 
> I have seen similar pattern for other libraries in Sandbox.
> 
> It tells me that either these libraries can be build *only* from
> within Boost tree or, if user wants to build them from outside
> Boost tree, it is required to specify the mysterious BOOST_ROOT which in
> fact should not be required at all [1]
> 
> [1] http://lists.boost.org/boost-users/2004/09/7755.php
> 
> It also suggests me that for cases as the one illustrated with Jamfile
> from the ITL library, if a user doesn't copy a library in to Boost tree
> or doesn't set BOOST_ROOT or doesn't put the hack of hard-coded
> Boost headers path as <include> in user-config.jam file, then it is not
> possible to compile such library (or its examples or tests, if it's
> headers-only).

Well, right. sandbox library should have some way of finding Boost, after all.

> I started to ask myself: How folks compile libraries while reviewing if
> these libraries are configured to locate headers with
>         <include>../../..
>         <include>$(BOOST_ROOT)
> 
> Does it mean a library submitted to review (or reviewed and accepted but
> not yet included to Boost) are required to be configured as living in
> Boost tree?
> Or, does it mean everybody makes "unofficial" configurations to
> environment like setting $BOOST_ROOT or hacking user-config.jam.
> 
> 
> Now, here comes final question derived from all the elaborate introduction:
> 
> If I assume that a user installs Boost without making any of the not
> recommended hacks to his environment (let's say, only puts use-project
> boost directive to user-config.jam), then
> How should I configure Jamfiles of Boost Geometry (examples and tests)
> to locate Boost headers in the following two situations:
> 
> 1) User copies Boost Geometry in to Boost tree and compiles examples and
> tests
> 
> 2) User keeps Boost Geometry outside Boost tree and still should be
> able to compile examples and tests using his Boost installation.

Both cases can be handled by adding /boost//headers in the sources of
your library. In case (2) it will work because user-config.jam has
'use-project' -- as discussed on IRC. Case (1) will work as well,
because Jamroot has this:

        project boost : ...

which also makes "/boost" a valid project id.

Ideally, each sandbox library would contain some logic to detect if project
named 'boost' exists, and if not so, to emit clear instructions what to
do. I can create a 'template' library in sandbox having such code, if
that helps.

- Volodya