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

Subject: Re: [Boost-build] [doc] b2 headers
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-04-09 19:03:41

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:
>>
>> I've been looking for documentation about purpose of command
>>
>> b2 headers
>>
>> Greping for headers or modular inside  /tools/build/doc and
>> /doc gives me nothing, so I blindly assume the unsearchable
>> https://www.boost.org/build/ does not explain it either.
>>
>> The magic of https://www.google.com/search?q="b2+headers"
>> brought this page to my attention:
>> https://www.boost.org/doc/libs/master/tools/boostdep/doc/html/
>> where, to my surprise, I find one of best intro to the concept
>> of modular Boost including very helpful explanation of the virtual
>> /boost directory and role of b2 headers command.
>>
>> Why this kind of information is presented in docs for somewhat
>> exotic to Boost (end)users command, I have no idea.
>
>   `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

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

>   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

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net