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

From: Peter Foley (peter_at_[hidden])
Date: 2007-09-05 02:00:07

Roland,

Thanks for the feedback.  (Comments inline.)

> From: Roland Schwarz <roland.schwarz_at_[hidden]>
> 
> Sorry to tell you, but I see a couple of things:
> 
> 1) bjam _is_ _not_ boost build, so the phrase:
>     BJAM - Is a synonym within this document for Boost.Build.
>     has the potential to confuse users.

Could you please explain what is wrong with the statement?  Obviously I
am confused myself then =p.

Would it make more sense to change the heading of this section to
"Definitions used in this document"?

> 
> 2) The title:
>     How do I run Boost Build standalone from the Boost Software
Library
>     is misleading insofar, as you still need a copy of the boost
> library.
>     boost-build.jam is not boost-build, it's just a pointer to it.
>     (Or did you mean to use a copy of BOOST_ROOT/tools/build/v2
> subdir?)

Obviously I was not clear enough within the document.  Technically you
do not need the whole of Boost to get Boost Build to work!  Download the
Nightly snapshot and see exactly what it contains and you see that it is
not a whole boost distribution!  Obviously there is a lot of extra stuff
in here you could do without.  I am no expert but from a very
rudimentary look I would think all you need to get Boost Build to work
would be (Note: I am just looking within the Zip file):

*	(mandatory files) boost-build.jam, build-system.jam and
bootstrap.jam
*	(optional files) user-config.jam and site-config.jam (you could
if you wanted to pass all these options as parameters to BJAM)
*	(mandatory folders and contents) build, kernel, options, tools
and util

If you had these files and folders in the same directory layout with a
compiled version of the bjam executable you could use the Boost Build
system to build whatever you wanted!

> 
> I tried to understand how your setup is supposed to work, but have to
> admit I need a little longer to understand the details.
> 
> Perhaps I can look into it this evening.

Please do.  From your comments I am very interested if some of my
assumptions are incorrect and if they are I would like to know!

> 
> However one warning:
> 
> bjam's behaviour with regard to BOOST_BUILD_PATH has been changed.
> It now will try to pick up user-config.jam and site-config.jam
> from the directory where the boost-build rule will point to _first_.
> So if you have user-config.jam files there they will be used instead
of
> yours.

Really?  This really should be mentioned somewhere in the documentation.
Taking a look here:
http://www.boost.org/doc/html/bbv2/reference.html#bbv2.reference.general
it does not imply that this is the case.  I know it is an assumption but
if you look at Table 25.2 (from the link above) I assumed that it looked
for the file in the order specified there within the table?  (eg
"%HOMEDRIVE%%HOMEPATH%" then "%HOME%" and then "%BOOST_BUILD_PATH%")

> 
> Since the nightly snapshot will have default files there, these will
be
> used instead of the others that follow later in BOOST_BUILD_PATH.

In this instance it's not so bad as the nightly Boost Build snapshot has
a fully commented out user-config.jam and site-config.jam files.

> 
> Please try this out with a bjam executable that you have compiled from
> trunk!

I assume that the nightly snapshot is (at a maximum) 24 hours old and as
you can see from my WIKI entry I used the nightly snapshot for the guide
for the 3rd, Sep 2007.  So unless this has changed in the last two days
I think it's pretty safe.

> 
> To pick up specific user-config.jam files you should use the new env.
> variable: BOOST_BUILD_USER_CONFIG instead.

I will update the WIKI entry to recommend setting this.  Just goes to
show what you miss out on if you only skim through the Boost-Build
mailing list to catch up.  Once again the main Boost Build documentation
should be updated there is no mention of this new environment variable
anywhere in the documentation.

As an aside I did a Google search
(http://www.google.com.au/search?q=BOOST_BUILD_USER_CONFIG) for
"Boost_BUILD_USER_CONFIG" and only got back 9 results.  All of these
were mail group postings!

> 
> Therefore to achieve the desired effect all you need is to set two
> environment variables:
> 
> SET BOOST_BUILD_PATH=/Path/to/a/copy/of/v2/subdirectory/of/boost/build
> SET BOOST_BUILD_USER_CONFIG=/Path/to/my/custom/user-config.jam
> 
> You will not need any boost-build.jam tricks. (This file is meant for

=p, the funny thing is I was not really doing any tricks!  My WIKI
article shows you how to isolate the BJAM.exe, boost-build.jam,
user-config.jam and site-config.jam files and set up the environment
variables.  So that you have a stable version of Boost Build.

> being part of a project, so a project could enforce to use it's own
> private copy of the build system. You should not try to circumvent
> this externally.)

Which is the whole point of my WIKI entry.  Trying to clearly explain
what needs to be done to do this and propose a way to manage migrating
to newer versions of the Boost Build System.

Once again thanks for the feedback and keep it coming!

Peter.