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

From: Peter Foley (peter_at_[hidden])
Date: 2007-09-05 18:59:20

Hi Roland,

> Date: Wed, 05 Sep 2007 16:40:24 +0200
> From: Roland Schwarz <roland.schwarz_at_[hidden]>
> 
> Please use the name "Boost Build" then to refer to the whole thing.
> "bjam" is just an implementation detail.
> There are rumours of an upcoming Boost Build that will have no
> resemblance  with bjam any more, since it will be
> implemented in python. You also would not say: I build with python
> then,
> but just continue to use the name
> "Boost Build".
> bjam just is kind of an interpreter that runs the Boost Build
> application.

Fair enough I can substitute "Boost Build" in everywhere if that is the
common consensus.

Just one last point though when we (ie the Boost Build community)
compare Boost Build to other build systems do we compare ourselves to
the whole support structure (ie any additional files that it calls to do
its work?) for MAKE, CMAKE, SCONS, NMAKE, ANT, ... 

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

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

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

This was the whole point for me asking for people to review the WIKI
entry!  So we can use the collective knowledge of those who use Boost
Build to ensure that the entry is correct, concise and useful. 

Maybe the way forward for this issue is to have a changelog file with
changes that an end user can check?  This way more formal documentation
can be updated later but the end user can get the benefits!  I assume
that this variable was added for the end users benefit?

> But please try to understand the full story first before telling
> others.

Unfortunately this won't help the Boost Build community!  From casual
reading this list and the Boost Developers list I often see comments
from people who should know that there are an extremely limited number
of people who actually know everything there is to know about Boost
Build (You might be one of them!).  I have seen requests for help
updating and improving the documentation of Boost Build (Hence my
efforts).

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!

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!

Peter.