How to specify Boost headers location properly
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
AMDG Mateusz Loskot wrote:
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) ;
<include>$(BOOST_ROOT) can be replaced with <dependency>/boost//headers In Christ, Steven Watanabe
Steven Watanabe wrote:
Mateusz Loskot wrote:
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) ;
<include>$(BOOST_ROOT) can be replaced with <dependency>/boost//headers
Yet another option I've just learned, but... What is the difference between using headers-only library by specifying this requirement using <source> and <dependency>? The manual says: "(...)a dependency on the target (...) (so it will be brought up-to-date whenever the target being declared is). The dependency is not used in any other way." What does bringing up-to-date mean for headers-only? Also, the "not used in any other way" suggests to me that it does not implicitly update <include> directories. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
Mateusz Loskot wrote:
Steven Watanabe wrote:
Mateusz Loskot wrote:
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) ;
<include>$(BOOST_ROOT) can be replaced with <dependency>/boost//headers
Yet another option I've just learned, but...
What is the difference between using headers-only library by specifying this requirement using <source> and <dependency>?
The manual says:
"(...)a dependency on the target (...) (so it will be brought up-to-date whenever the target being declared is). The dependency is not used in any other way."
What does bringing up-to-date mean for headers-only? Also, the "not used in any other way" suggests to me that it does not implicitly update <include> directories.
Actually, for /boost//headers there's no difference between <source> and <dependency>. Every single metatarget in Boost.Build, when built, produces two things: - actual targets (corresponding to files) - set of properties that must be propagated to dependents. These are known as usage requirements. Now, there are three predefined build properties: 1. <source> tries to consume the produced targets, and adds usage requirements. 2. <dependency> sets a dependency on the produced targets, and also adds usage requirements. 3. <use> only sets usage requirements Now, because the 'headers' metatarget never produces any real file, only usage requirements, all three are exactly the same. - Volodya
Vladimir Prus wrote:
Mateusz Loskot wrote:
Steven Watanabe wrote:
Mateusz Loskot wrote:
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) ;
<include>$(BOOST_ROOT) can be replaced with <dependency>/boost//headers
Yet another option I've just learned, but...
What is the difference between using headers-only library by specifying this requirement using <source> and <dependency>?
The manual says:
"(...)a dependency on the target (...) (so it will be brought up-to-date whenever the target being declared is). The dependency is not used in any other way."
What does bringing up-to-date mean for headers-only? Also, the "not used in any other way" suggests to me that it does not implicitly update <include> directories.
Actually, for /boost//headers there's no difference between <source> and <dependency>. Every single metatarget in Boost.Build, when built, produces two things:
- actual targets (corresponding to files) - set of properties that must be propagated to dependents. These are known as usage requirements.
I understand.
Now, there are three predefined build properties:
1. <source> tries to consume the produced targets, and adds usage requirements. 2. <dependency> sets a dependency on the produced targets, and also adds usage requirements. 3. <use> only sets usage requirements
Now, because the 'headers' metatarget never produces any real file, only usage requirements, all three are exactly the same.
It makes perfect sense to me now. Great, I think I know how to configure Boost.Geometry examples and tests now. Thank you to you and Steven! -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
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
On 10 March 2010 22:01, Vladimir Prus <ghost@cs.msu.su> wrote:
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.
If you could fix up the example I created, that would be great. It's at: https://svn.boost.org/svn/boost/sandbox/example I used João Abecasis' script to find boost, but you might be able to do something better? Daniel
Daniel James wrote:
On 10 March 2010 22:01, Vladimir Prus <ghost@cs.msu.su> wrote:
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.
If you could fix up the example I created, that would be great. It's at:
https://svn.boost.org/svn/boost/sandbox/example
I used João Abecasis' script to find boost, but you might be able to do something better?
The question is whether we should? Putting use-project /boost : some-path ; in user-config.jam is one-time effort, and is probably more reliable than environment variables anyway. - Volodya
On 10 March 2010 22:17, Vladimir Prus <ghost@cs.msu.su> wrote:
The question is whether we should? Putting
use-project /boost : some-path ;
in user-config.jam is one-time effort, and is probably more reliable than environment variables anyway.
Whatever you think is best is fine with me.
Vladimir Prus wrote:
Daniel James wrote:
On 10 March 2010 22:01, Vladimir Prus <ghost@cs.msu.su> wrote:
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.
If you could fix up the example I created, that would be great. It's at:
https://svn.boost.org/svn/boost/sandbox/example
I used João Abecasis' script to find boost, but you might be able to do something better?
The question is whether we should? Putting
use-project /boost : some-path ;
in user-config.jam is one-time effort, and is probably more reliable than environment variables anyway.
By the way, what is it possible for user to specify this setting in site-config.jam, so it's easier to have various projects configured to use various versions of Boost installed in user's system? Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
Mateusz Loskot wrote:
Vladimir Prus wrote:
Daniel James wrote:
On 10 March 2010 22:01, Vladimir Prus <ghost@cs.msu.su> wrote:
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. If you could fix up the example I created, that would be great. It's at:
https://svn.boost.org/svn/boost/sandbox/example
I used João Abecasis' script to find boost, but you might be able to do something better? The question is whether we should? Putting
use-project /boost : some-path ;
in user-config.jam is one-time effort, and is probably more reliable than environment variables anyway.
By the way, what is it possible for user to specify this setting in site-config.jam, so it's easier to have various projects configured to use various versions of Boost installed in user's system?
This can be done in site-config.jam, but it's not clear to me why is that better. In fact, site-config.jam is probably was too smart idea -- the intention was that 'system administrator' could put various definitions there to help users, but most users are end users, so don't need to touch that file. - Volodya
Vladimir Prus wrote:
Mateusz Loskot wrote:
Vladimir Prus wrote:
Daniel James wrote:
On 10 March 2010 22:01, Vladimir Prus <ghost@cs.msu.su> wrote:
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. If you could fix up the example I created, that would be great. It's at:
https://svn.boost.org/svn/boost/sandbox/example
I used João Abecasis' script to find boost, but you might be able to do something better? The question is whether we should? Putting
use-project /boost : some-path ;
in user-config.jam is one-time effort, and is probably more reliable than environment variables anyway.
By the way, what is it possible for user to specify this setting in site-config.jam, so it's easier to have various projects configured to use various versions of Boost installed in user's system?
This can be done in site-config.jam, but it's not clear to me why is that better.
I'm not suggesting it is better idea. Perhaps I mis-suggested that due to lack of understanding of purpose of this file.
In fact, site-config.jam is probably was too smart idea -- the intention was that 'system administrator' could put various definitions there to help users, but most users are end users, so don't need to touch that file.
I see. Right then, user-config.jam is the right place for setting Boost location. Thanks! -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
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
participants (4)
-
Daniel James -
Mateusz Loskot -
Steven Watanabe -
Vladimir Prus