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

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

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, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org