Re: boost-build.jam documentation issues

From: David Abrahams (dave_at_[hidden])
Date: 2005-08-10 14:20:48

Andrey Melnikov <melnikov_at_[hidden]> writes:

> Weining Hao wrote:
>> About the project out of /boost, for example
>> /home/hnn/t1, I copy the same Jamefile.v2,
>> measkern.qbk and the directory HTML to here and run
>> bjam --v2, it says:
>> 
>> Unable to load Boost.Build: could not find
>> "boost-build.jam"
>> ---------------------------------------------------------------
>> Attempted search from /home/hnn/t1 up to the root
>> and in these directories from BOOST_BUILD_PATH and
>> BOOST_ROOT: /usr/share/boost-build.
>> Please consult the documentation at
>> 'http://www.boost.org'.
>
> The questions below are for BB developers. I'd like to address the
> problem in the documentation and to make the documentation clearer
> to prevent such questions to in the future.

I'm very glad to hear that. In the next week I have to prepare a
presentation about building and testing Boost, and I'm going to need
to review and understand all the documentation. Maybe we can work
together to whip it into shape.

> What is /usr/share/boost-build? Did this path came from the
> environment variables? It looks just like the default BB search path
> on Unix. If it's the default location, the message should be
> changed.

This is due to the unfortunate exposure of an impelementation detail
to users. http://groups.yahoo.com/group/jamboost/message/10103
explains.

> Also we could direct users directly to 
> http://www.boost.org/doc/html/bbv2.html

That's a good idea. Would you like CVS write privileges?

> The documentation is in three places again:
> http://www.boost.org/tools/build/jam_src/#jambase_replacement

This describes the low-level behavior of the bjam tool; we don't
really want that exposed in the regular documentation. 

Also, I think we may be doing a few too many "smart" things at
startup. At least we can throw out the BOOST_ROOT business.

> http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/reference.html#bbv2.reference.init

That's the right documentation for users of BBv2.

> http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/installation.html

IMO it's perfectly appropriate to have some repetition of this
information here, in a tutorial about installing BB..

> Are the last two documents taken from CVS?

Yes.

> Should http://www.boost.org/tools/build/jam_src/ be merged into bbv2 
> documentation tree some day?

Probably not. We want to move off of the jam substrate onto a rewrite
based on Python as soon as BBv2 can replace BBv1. If any of the
documentation at http://www.boost.org/tools/build/jam_src/index.html
is still relevant after the Python translation is done, then by all
means, let's move it.

> Some comments regarding doc/html/bbv2/reference.html#bbv2.reference.init
>
> > bjam's first job upon startup is to load the Jam code that implements 
> > the build system. To do this, it searches for a file called
> > boost-build.jam, first in the invocation directory, then in its 
> parent > and so forth up to the filesystem root, and finally in the 
> directories > specified by the environment variable BOOST_BUILD_PATH.
>
> What is "invocation directory"? Is this the current directory, 

Yes, the current directory at the time bjam was invoked. I thought
that would be clearer than "current" since some people might be
confused by that term.

> the directory where Jamfile is located or the directory where
> bjam.exe is located?
>
> What is better in English - to say "environment variable 
> BOOST_BUILD_PATH" or "BOOST_BUILD_PATH environment variable"?

The latter, prefaced by "the."

> > When found, the file is interpreted, and should specify the build
> > system location by calling the boost-build rule:
> >
> > rule boost-build ( location ? )
>
> This is boost-build rule declaration syntax. Users don't need to declare 
> a new boost-build rule. They even don't need to know the declaration 
> syntax. They only need to know what to put into boost-build.jam. So we 
> should have just
>
> boost-build /usr/share/boost-build/kernel

Indeed.

boost-build <replaceable>path/to/boost-build</replaceable> ;

would be more appropriate, though. Many people don't end up with
Boost.Build in that directory.

> there. The last /kernel part isn't obvious. 

It isn't right either.

boost-build /usr/share/boost-build ;

would be correct for an installation of BBv2 in
/usr/share/boost-build.

> We should mention in the documentaion that the path isn't to bb
> installation root, but to kernel directory where bootstrap.jam can
> be found. Should BOOST_BUILD_PATH point to /kernel too?

Nope and nope. I understand why you were misled by the
boost-build.jam in the top BBv2 directory.

> > For example, if the build system files were located in a directory
> > "build-system/" at your project root, you might place a
> > boost-build.jam at the project root containing:
> >
> > boost-build build-system ;
>
> The example is pretty useless.
>
> Firstly, build-system looks too similar to boost-build and doesn't look 
> like just a filesystem path.

Yes, I went through the docs and tried to fix a bunch of similar
issues a while ago. I'm not sure if I missed that one or if it
slipped back in somehow.

> Secondly, "build-system" is too similar to "kernel" which users can see 
> in the default boost-build.jam located in bbv2 installation root folder.
>
> Thirdly, it should read as "build-system/kernel". Renaming kernel 
> subfolder to something other is practically useless.

Forget about kernel; users don't need to know about it.

> Also, what is the reason to have so many boost-build.jam files? I think 
> we can live just with the file located at root.

Which ones are you talking about? The one in the root of BBv2 is used
to forward its work on to the one in kernel/

> > In this case, running bjam anywhere in the project tree will
> > automatically find the build system.
>
> This sentense is misleading. It sounds like boost-build.jam was
> designed for per-project configuration, and user will have to have
> boost-build.jam in all her projects.

That's one acceptable way to do it.

> In most cases boost-build.jam should be put into the user's 
> project-root, into the directory where the user stores all his projects, 
> shouldn't it?

Yes, that was one of the design goals. The sentence should be
amended.

> > The default bootstrap.jam, after loading some standard
> > definitions, loads two files, which can be provided/customised by
> > user: site-config.jam and user-config.jam.
>
> There's no such thing like a non-default bootstrap.jam. There's only
> one bootstrap.jam, and there are no reasons to have many.

In fact, users shouldn't even know about bootstrap.jam.

> The fact that bootstrap.jam "loads some standard definitions" is
> obvious and doesn't provide additional information to the user. So
> the phrase should be removed or replaced with something more
> meaningful.

Agreed.

> It isn't clear that user-config is optional. Also it isn't clear why 
> there are so many configs and how such a diversity can help user to 
> solve his problems. So typical usage scenarios should be put here.

Agreed again.

> > Locations where those files a search are summarized below:
> >
> > Table 26.1. Search paths for configuration files
>
> The shell is rarely used on Windows. %% syntax is uncommon to most of 
> the users. Recommended way to set per-user or per-site environment 
> variables is through GUI. Most users know only basic shell syntax and 
> won't be able to guess that %HOMEDRIVE%%HOMEPATH% is a string 
> concatenation and really their profile directory is meant.

That may be true, but 26.1 isn't the tutorial anymore. Most people
shouldn't be reading this section of the documentation unless they
need to understand the low-level details of the build system. We want
the information to be complete and precise enough for people who want
to understand exactly which directory is being referred to. Can you
think of a better rephrasing for that audience?

> %SystemRoot% is <drive>:\WINDOWS or <drive>:\WINNT. Do you really 
> suggest to put something into windows system folders? Or actually 
> %SystemDrive%\ is meant?

According to the code, it's SystemRoot

path = [ modules.peek : SystemRoot ] $(user-path) ; 

Is there a better default place for a site-wide configuration on
Windows?

> > Boost.Build comes with default versions of those files, which can
> > serve as templates for customized versions.
>
> The files aren't "default" because they cannot be used as is. 

Sure they can. You can create just a user-config and allow the
system's site-config to take effect. What problem are you referring
to?

> We should say here that they are just templates.
>
> Does http://www.boost.org/doc/html/bbv2/recipies/site-config.html
> really mean "recipes"? Is there a way to fix this or CVS doesn't
> allow us to rename directories without losing version history?

The current version is at
http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/recipies.html
and fortunately, the HTML isn't stored in CVS -- the directory and its
contents are generated by BoostBook. I think it should be simple
enough to fix the xml so the spelling is right.

> I'm going to update BB TODO list and my Getting Started guide in
> Wiki accordingly to the results of this discussion when it is
> finished. I could also contribute to the documentation, but at the
> moment my todo list is too long.

I'll try to make some of the fixes as we go along.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com