From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-08-12 04:51:57
On Saturday 23 July 2005 14:36, Alo Sarv wrote:
> >>5. Just a note about the manual from someone who just spent 4 days
> >>learning BB - BBv2 manual IS a lot better than v1 one, but the
> >>organization is bit rough, it's hard to find specific things in it, so
> >>you end up clicking through all the pages each time you need a specific
> >>thing. You can't just hop in there to look up a single thing, you'd have
> >>to read the entire manual in detail (at least once) to get the features
> >>overview ...
> > Can you suggest the organization that would work better for you?
> 1. In the beginning of Tutorial, start out with something like is shown
Noted, I've added your suggestons to
> 7. Writing custom targets (I think I'm refering to "rules" actually
> here) - e.g. 'install' rule, which should copy files to system. Speaking
> of which - I don't see any reference of such commands, e.g. FileClone,
> SymLink, MkDir etc - in the manual.
That's because MkDir is not supported. Symlink is supported and deserves a mention.
> Overall, if you look at the manual index we currently see:
> * Tutorial
> * User documentation
> * Extended Manual
> * Detailed Reference
> * FAQ
> In tutorial section, it's normal to leave out feature listings, and
> focus on getting minimal examples running; altough I would recommend
> starting out with a full example (including all required files), and
> then explaining it line-by line, instead of showing snippets of code in
> each page.
> What exactly is the difference between UserDoc, ExtMan and DetRef ?
> Which one should I search if I want to do X ? Or Y ?
I agree this distinction does not work.
> What about hierarchy like this:
> 1. Getting Started
> [ includes installation and tutorial, with 1-2 small, but complete
> examples (points 1. and 2.) ]
What I'd prefer is this:
- "Hello world" -- a single Jamroot project
- Project structure.
Some real-looking example with Jamroot and child Jamfiles
- Libraries -- how to declare and how to use
- Testing -- the "unit-test" rule
- Installing -- the "install" rule
So that this covers much of lifecycle of project.
> 2. Writing Jamfiles
> [ includes detailed reference of what you can do with Jamfiles, e.g
> targets, variables, dependencies, projects; starting simple, moving
> towards more complex things (3, 4, 5) ]
> 3. Invoking Bjam
> [ includes detailed reference on command-line arguments, how bjam
> scans Jamfiles in folders; how it works to achieve targets;
> multi-threaded compilations; what other black magic can one do from
> commandline (overriding compile-commands, etc) (6) ]
> 4. Extending Boost.Build
> [ includes overview of the tools/v2/ folder's contents; when/how to
> write custom jam code - e.g. new toolsets, OS features, custom
> targets (QT's uic / moc are good examples for this) (7, 8) ]
I think this organization is fine. The biggest question now is
detailed structure of section 2. Topics should include:
- Language reference (current (just added)
- Features and properties
- Declaring targets (current
- Builtin features
- Shared/static libraries
- testing rule
- install rules
- low-level rules (make and notfile)
- declaring project constants
> 5. Frequently Asked Questions
> [ no changes needed ]
> Another thing that I was unable to find in this manual was actual Jam
> language reference - had to do some googling around to find something on
> it; maybe there was a link somewhere in the manual, but I couldn't find
> it; anyway, shouldn't a build-system manual also include reference
> manual of the actual language used to extend the build system? External
> link would be sufficient.
I've just committed a change with jam langauge overview.
-- Vladimir Prus http://vladimir_prus.blogspot.com Boost.Build V2: http://boost.org/boost-build2
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk