Boost logo

Boost :

Subject: Re: [boost] How to specify Boost headers location properly
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-03-10 19:04:38

Hi Volodya,

Vladimir Prus wrote:
> 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
>> 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.

OK, I've got it well confirmed what I supposed.
I admit I've been just copying and pasting bits of various
Jamfiles, without deeper considerations of what I'm
until now.

>> 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
>> :
>> 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]
>> 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.

Yes, true, but there probably is a proper way :-)

>> 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.

That's exactly the knowledge I've been missing.
Makes perfect sense.

> 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.

I think it would be very useful.

Volodya, thank you very much for helping me to solve this with patience,
here and on #boost.

Best regards,

Mateusz Loskot,
Charter Member of OSGeo,

Boost list run by bdawes at, gregod at, cpdaniel at, john at