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:
> 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
> 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
> 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
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:
> exe overlap_counter
> 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 
>  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
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
> 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
> 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
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk