Boost logo

Boost-Build :

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-07-06 09:39:38

Vladimir Prus wrote:
> On Sunday 19 June 2005 02:12, David Abrahams wrote:
>>It seems a bit weird that --help-usage shows me the options and
>>--help-options shows me... something else. Am I missing something?
> I don't understand this either. I think the --help output should be no longer
> than this:
> Boost.Build V2 Milestone whatever.
> For basic command line syntax use:
> --help-command-line
> For information on building this project use:
> --help-project
> For Boost.Build internal documentation use:
> --help-internals
> The --help-project would print the value of 'project-help' constant in the
> current Jamfile, and the output of --help-command-line will be:
> Command line syntax:
> bjam [options] [properties] [targets]
> Options, properties and targets can be specified in any order.
> To build all targets in current Jamfile:
> bjam
> To build target 'foo' in directory 'sub' in debug and release variants:
> bjam variant=release variant=debug sub//foo
> To rebuild a single file in current project:
> bjam -a foo.o
> Important options:
> --clean Remove the named targets
> -a Rebuild everything
> -n Don't execute the command, only print them
> -d+2 Show all executed commands
> -q Stop at first error
> The idea is that --help should not list too many information that's no needed
> for ordinary users. Comments?

I think that right there you have a problem. I would consider the "-a"
and "-n", options that ordinary users would be interested in. And given
that you labeled them under "Important options:" also points to you
thinking the same. Also using "--help-project" just adds another step
for the user to what I would consider *very* important information which
I would put ahead of all others.

Ideally what we want to do is show information from most to least
important. The least important information can be hidden behind
additional --help-* invocations. I would prefer that --help show
something like:


[scanned Jamfile docs here]

You can use "--help-project" to obtain additional information
on this project.

Important Options:

* --clean; Remove the named targets
* -a; Rebuild everything
* -n; Don't execute the command, only print them
* -d+2; Show all executed commands
* -q; Stop at first error

Available Help:

These are the available options for obtaining documentation. Some
options have additional instructions on how to get more detailed
information. Multiple options are allowed and sometimes required.
For example, the options that configure the help system still
require a regular help request option for any output to be

* --help; This help message.
* --help-project; Information on building for this project.
* --help-command; Command line syntax and available options.
* --help-doc; How to control the output of this help text.
* --help-internal; Boost.Build implementation details.

And no I don't mind that the initial help is long. I'd rather err on the
side of too much information rather than have users be discouraged.

> BTW, I don't like the current way options are handled. In
> kernel/bootstrap.jam, we loop over all ARGV elements. If it matches --.* we
> look for a module in the "options" directory. If found we load it and call
> the 'process' methods.
> Two problems:
> 1. Given that there's a single module in the 'options' dir, the above look
> like overgeneralization.

But what happens when we have more than one module in the 'options' dir?
We did it that way precisely because we wanted to support adding option
handling modules as needed.

> 2. I need to handle --help-project after user-config.jam is loaded, and that
> happens only in build-system.jam. The only approach I see is handling
> --help in build-system.jam, and that will make the logic in
> 'kernel/bootstrap.jam' just unused.

I just don't see the point of having the 'project-help' rule. It goes
against the current design of the 'doc' module and does not have
anything that the 'doc' module can't already do with the file scanning.
What I said before is still what I think is most flexible and fits with
the current 'doc' design. Once upon a time I wrote:

[ ] Make --help produce any help docs in the "boost-root.jam",
"site-config.jam", "user-config.jam", "boost-build.jam", root/Jamfile,
and subdir/Jamfile in that order.

And by "help docs" I mean the regular scanning for docs in comments that
we already do. No new rules required, and makes for consistent handling
of the docs. The only amendment I would now make to the above given the
context of this thread would be to split that into two parts:

a) Make --help produce any help docs in root/Jamfile and subdir/Jamfile,
integrated into the rest of the docs printed by the '--help' option as

b) Make --help-project produce any help docs in boost-root.jam,
site-config.jam, user-config.jam, boost-build.jam, root/Jamfile, and
subdir/Jamfile in that order.

-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. -
-- rrivera/ - grafik/
-- 102708583/icq - grafikrobot/aim - Grafik/

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