Re: [jamboost] Boost.Build doc request: more task-oriented material

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-05-23 09:24:44

----- Original Message -----
From: "Beman Dawes" <bdawes_at_[hidden]>

> Task-oriented documentation would, in one place, identify the steps the
> user needs to execute to accomplish the task. If the description of a
step
> is at all complex, there is a link to the reference docs for that step.

Yes, and we'll have something like that for v2. For now we were just trying
to triage the support requests for "how do I build boost??!?!" We're trying
not to do any additional work (including docs) for v1 that we don't need
to.

> For example, the user docs might have a section:
>
> How to do a release build
> -------------------------
>
> To do a "release" build, rather than the default "debug" style
> builds, invoke the build like this: bjam ...
>
> This is an example of a build variant. ["build variant" is a link]
> See List of Common Variants for other build variants. ["List of
> Common Variants" is a link]

Feel free to add that. You wrote the original user docs, after all ;-)

> Here are the particular tasks I need to accomplish, yet can't because
they
> involve pulling together so may different pieces of the current
> documentation:
>
> * How to I specify an additional compiler switch for one compiler from
the
> bjam command line? (I want to see the effect of running the regression
> tests with an additional compiler switch.)

Just add it to the BUILD request. If it's a raw compiler switch that's not
represented by a feature, you can use <cxxflags>additional-flags-here. If
you need to make any property specific to a particular toolset, use
<toolset><*><feature>value.

> * I want to add an additional compiler switch for all compiles with a
> certain compiler. What do I add to the toolset?

Just stick it in the <toolset>-C++-action and/or <toolset>-C-action build
actions; that should be fairly obvious from looking at the toolset.

> * I want to add an additional compiler switch for compiles with version
> 1.23 or later of a certain compiler. What do I add to the toolset?

Hah; good luck. How will Jam know which version of the compiler you're
using?
Better support for multiple toolset versions is planned for v2, but I doubt
we'll get *that* sort of automation any time soon.

If you're willing to ask users to set a global variable, you can define
different actions within an if/then statement depending on the variable
setting.

However, I usually end up making a new toolset using extends-toolset so I
can try both versions without getting subvariant collisions.

-Dave