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

Subject: Re: [Boost-build] [doc] b2 headers
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-04-09 20:01:32

On 9 April 2018 at 21:43, Steven Watanabe via Boost-build
<boost-build_at_[hidden]> wrote:
> 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.

Thanks for the excellent bearings.

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

It could be distilled to CONTRIBUTING.md,
maintained in https://github.com/boostorg/boost/
and released next to the Jamroot.

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

Awesome, thanks

Possibly, I translated the Getting Started wiki
steps sequence too literally
https://github.com/boostorg/boost/wiki/Getting-Started

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