Boost logo

Boost-Build :

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

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

The documentation is in three places again:

Are the last two documents taken from CVS?

Should 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

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



Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at