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
> 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
>>> b2 headers is discussed briefly here:
>>> 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).
Possibly, I translated the Getting Started wiki
steps sequence too literally
-- Mateusz Loskot, http://mateusz.loskot.net
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