Re: [Boost-build] [WIKI Entry] - How to run Boost Build standalone

From: Roland Schwarz (roland.schwarz_at_[hidden])
Date: 2007-09-06 03:39:36

Peter Foley wrote:
> Maybe this is why people are confused about using Boost Build.  They
> miss-understand and feel that it isn't a standalone build system (ie it
> is only used to build the Boost libraries!).

Sadly true :-(

I also started as a plain user who tried to set up boost build to use 
for building my own projects. I suddenly rushed into some problems, and 
started to read the code. And this was where I really began to like 
boost build despite its somewhat arcane syntax.

The authors of the build system have put in quite some unique nice ideas!

I found out (from reading the manual, from searching list, from reading 
the source - hint: there sometimes is important docs embedded) that most 
of the things I wanted to achieve already were built in!

Another hint: Vladimir Prus is a nice guy who usually hangs around on 
the #boot IRC channel and often gives a helping hand (Thanks Volodya).

>> Another note about the complaint of not having found anything about
>> BOOST_BUILD_USER_CONFIG.
>> You are on the bleeding edge, where documentation is sparse. It is
> fine
>> that you are trying to improve the situation.
> 
> I do not believe that this is a fair statement!!  As I stated in my
> original reply I based my user guide on documentation that made explicit
> references to the Boost Build system documentation.  In my previous
> email I was making the statement that there is nothing within the
> documentation mentioning this environment variable.  I except that by
> your definition this variable is on the Bleeding edge but if a user
> doesn't know about it to use it what is the point?

You are absolutely correct! This is why I said I appreciate your efforts 
to improve the situation.

> How as a user of the Boost Build system can I be blamed for not knowing
> about it if it is not in the documentation.  Especially since this would
> be the first place I check prior to asking on the mail list (as
> recommended when posting questions to the list).

Sorry, I did not intend to blame you for anything.

> Maybe the way forward for this issue is to have a changelog file with
> changes that an end user can check?

SVN _has_ a changelog.

Btw.: I just checked the documentation:
It clearly states that BOOST_BUILD_PATH and boost-build.jam's main 
objective is to locate the boost build system.
It is a side effect, that user-config.jam and site-config.jam are also 
loaded from there. And as you can see this happens as a last resort only.

Unfortunately (due to user requests) the search behavior of the 
BOOST_BUILD_PATH had been changed to allow "tricks" as you are trying to 
achieve.

Let me try to tell the full story:

bjam's documented behavior was to try to load the boost build files from 
the first place where it finds a bootstrap.jam file by searching the 
paths (yes plural) defined in BOOST_BUILD_PATH. the boost-build rule 
(found in boost-build.jam tacked itself in front of the paths.

Now since there are stock user-config.jam and site-config.jam files also 
in this place (as a last-resort fallback I guess) they have been picked 
up, no matter what the user put in BOOST_BUILD_PATH.

A first attempt to resolve this was to have the boost-build rule tack 
itself to the back of the BOOST_BUILD_PATH. This resolved the issue, but 
introduced another problem:

When you installed a stand-alone version of boost build (as I did by 
using the debian package) always this standalone version was picked up 
first. (/etc/boost-build always was first on BOOST_BUILD_PATH).

And this turned out to be really bad: I was not able to build the boost 
libraries any more :-( . The debian boost build just was too old to 
build HEAD boost revision. The whole purpose of boost-build.jam being 
able to specify an in-tree boost build system was defeated.

So I tried to resolve the problem by cleanly separate the concerns:

Use BOOST_BUILD_PATH to locate the build system.
Use BOOST_BUILD_USER_CONFIG to locate the user-config.jam

(Perhaps there also should a BOOST_BUILD_SITE_CONFIG env. var)

The next step was to contact the authors and ask them why the behavior 
was like it was (there were indeed good reasons), suggest a solution and 
try to convince them to accept the suggested fix.

Why did I tell you this story?
Well, this is a community project. People out here are usually _very_ 
willingly to help (I guess just as you are). But improving a situation 
needs communicating. This means to find out who is the author of a piece 
of software, try to contact him/her possibly sending a patch.

Please don't take the following as offensive: In your case I would 
rather liked to have seen that you grabbed the sources of the original 
documentation, tried to fix it and contact the authors. (I think there 
is no excuse like: I didn't know who the authors are. Just look into the 
files.) I repeat: no offense, this is just my personal preference.

I know this procedure can be burdensome at times, but the outcome is 
paying off: You didn't increase entropy but saved the next user the 
hassle to hunt for the important information in various places.

Hint: did you consider joining the IBD (Improving Boost Docs) team?
(Disregard this hint if you are already a member of it.)

> If the bar is set such that you must have a _full_ understanding of how
> Boost Build works prior to doing anything then I believe that asking for
> help from others is doomed to failure.  I personally don't have the time
> to invest in gaining a full understanding!

Again I appreciate your efforts! I just wanted to point out, that 
spreading half-truth just will rise the bar for others.

Let me try to give you an example:
There was an urgent need to update the "first steps" guide prior to 
release of 1.34. Altough I think I gained quite some knowledge about the 
process over time I did not dare to come up with such a guide.

I was very glad that David Abrahams himself finally wrote a very fine 
introduction. And I have to admit this guide was better than anything I 
would have been able to create. Sure, he is the one who possibly knows 
almost the whole story. And this puts him in a position where he can 
simplify explanations without stretching the truth too much.

I am almost sure the authors of the respective guides will appreciate 
it, if you send patches to the guides.

I hope I did not intimidate you too much, and if I did, remember this 
are just my personal thoughts.

> I will look at updating the guide tonight after work based on the
> feedback I have received.  Since the guide is posted to the Boost WIKI
> and it is a community resource I am happy for you to also update it!

Sorry , but this is another thing I dislike ( but sincerely respect ), 
wikiing. So I likely will not be there until there is a similar review 
system as we have for code reviews.

Roland aka speedsnail