[boost] How to specify Boost headers location properly

Subject: [boost] How to specify Boost headers location properly
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-03-10 15:25:34

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.

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

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.

By the way, I have started  discussing this [2] problem on Boost
Geometry mailing list but there are still some confusions [3] that
make this issue far from clarified.

[2] http://lists.osgeo.org/pipermail/ggl/2010-March/000657.html
[3] http://lists.osgeo.org/pipermail/ggl/2010-March/000662.html

I'd appreciate if someone here could teach me, once and for good,
how to make it right.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org