[jamboost] boost-build.jam documentation issues

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-08-09 14:27:14

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.

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.

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

The documentation is in three places again:
http://www.boost.org/tools/build/jam_src/#jambase_replacement
http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/reference.html#bbv2.reference.init
http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/bbv2/installation.html

Are the last two documents taken from CVS?

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

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

> 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

there. The last /kernel part isn't obvious. 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?

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

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.

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.

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

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?

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

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.

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.

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

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

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

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.

Andrey