Boost logo

Boost-Build :

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-07-06 10:33:52

Vladimir Prus wrote:
> On Wednesday 06 July 2005 18:39, Rene Rivera wrote:
>>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.
> What would --help-project produce in addition to 'scanned Jamfile docs'? Whole
> site-config.jam/user-config.jam/.... hierarchy?


> And if I run bjam in
> libs/filesystem/build and Jamfile has no docs, will I see Boost-wide docs, or
> not?

Yes, i.e. what I refer to below as "root/Jamfile".

>>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
>> generated.
> Probably this text is too long. Will it hurt much if we retain just the first
> sentence?

No, I don't think it would hurt. We would have to move that explanation
someplace else though, possibly into --help-command?

>>>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.
> I think that since we don't have any other modules, this is premature
> generalization.

Possibly, but is it costing us anything at this point? There was a time
when I had another module in options, for manipulating toolsets, it was
lost in the sands of computer upgrades though.

>>>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.
> Ah, I did not understood this part of your suggestion.
>>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
> In what order?

Good question... Most to least specific might be the best choice to be
consistent, i.e. subdir/Jamfile then root/Jamfile. But the other way
might read better for people. I'd say we do it most-to-least and
consider the other way when we can see the docs in action.

>>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.
> Ok, this suggestion seem OK with me. The only issue (and that's why I've
> suggested separate rule in Jamfile), is that I don't yet quite understand the
> scanning of docs. Is it easy to add scanning of Jamfiles to doc.jam?

Very easy. Actually doc.jam doesn't know anything about finding files.
All it does it given a file it will scan and print out the docs. The
finding of files is currently done in options/help.jam and it just calls: ( modules-files + : action * )

So if we have the paths to the Jamfiles we can just call the do-scan
rule: path-to/Jamfile : print-help-module ; The
print-help-module just prints the help docs at the top of the file.

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