Re: [Boost-build] [doc] b2 headers

Subject: Re: [Boost-build] [doc] b2 headers
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2018-04-09 19:43:47

AMDG

On 04/09/2018 01:03 PM, Mateusz Loskot via Boost-build wrote:
> On 9 April 2018 at 19:27, Steven Watanabe via Boost-build
> <boost-build_at_[hidden]> wrote:
>> On 04/09/2018 07:35 AM, Mateusz Loskot via Boost-build wrote:
>>>
>>   `b2 headers` is not really intended for end users.
>> It's only relevant when working from git as the
>> packaged releases have all the headers moved into
>> boost/ to begin with.
> 
> I should have said, an advanced power end-user with potential for
> Boost contributor :)
> 
>>  As a result, the obvious
>> places to put this documentation (the getting started
>> guide and `b2 --help` from $BOOST_ROOT) are not really
>> correct.
>>
>>   b2 headers is discussed briefly here:
>> https://github.com/boostorg/boost/wiki/Getting-Started
>> which is about as good a location as anywhere.
> 
> 
> AFAIC count, that makes 3 if not 4 places to learn about Boost and
> non-Boost-specific  features of Boost.Build
> 

- b2 --help: A quick reference for building Boost.  This
  must not contain any information that is not also
  documented elsewhere.
- boost.org/build: Documentation of Boost.Build itself.
  Ideally you shouldn't need this unless you're writing Jamfiles.
- getting started guide: Everything you need to know for
  working with a packaged release of Boost.
- github wiki: Documentation specific to working from git.

> IMHO, use of GitHub wiki for such important documentation should be simply
> forbidden, for sake of decreasing docs dispersal.
> 

  Historically, we've used the wiki for a lot of
documentation targeted at Boost developers.
This page was originally migrated from trac.
I think this information should be separate
from the getting started guide, although
where it should actually live is open to debate.

>>   Also, most of the time, you don't need to care
>> about `b2 headers`.  Running b2 in $BOOST_ROOT
>> will build the headers in addition to putting
>> the libraries in stage/lib.  For internal use
>> such as Boost tests and examples, the necessary
>> headers will be created automatically.
> 
> I disagree. Most of the time, as a contributor to Boost.X,
> I don't care about all the Boost libraries but X.
> So, I'm indeed interested in building as little as possible:
> 
> b2 headers
> cd libs/x
> b2 test
> 

  If that's all you're doing, then you can skip
b2 headers.  b2 test will run (part of) b2 headers
on demand.  (To be precise, it will update any
headers that are found by the #include scanner).

In Christ,
Steven Watanabe