[doc] b2 headers

Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

[doc] b2 headers

Boost - Build mailing list
Hi,

TL;TR: A rant


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.
But, as long-time Boost.Build users, I dare to judge this is an
excellent example of why peole hate this awesome build system :)

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
On Mon, Apr 9, 2018 at 8:35 AM, Mateusz Loskot via Boost-build <[hidden email]> wrote:
Hi,

TL;TR: A rant


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.

You could search here instead <https://grafikrobot.github.io/b2doc/>. 

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.
But, as long-time Boost.Build users, I dare to judge this is an
excellent example of why people hate this awesome build system :)

"b2 headers" is an entirely Boost C++ Libraries specific construct and other than using b2 has nothing to do with b2 itself. The same applies to all the rest of that documentation you just pointed out :-) And hence why it's not in the b2 documentation. Hence what you are actually saying is that people hate the Boost C++ Libraries setup and not b2. And I don't blame them.. I don't like it either ;-) Which is why I've been working to put as much distance between Boost C++ Libraries and b2.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
On 9 April 2018 at 16:09, Rene Rivera <[hidden email]> wrote:

> On Mon, Apr 9, 2018 at 8:35 AM, Mateusz Loskot via Boost-build
> <[hidden email]> wrote:
>>
>> TL;TR: A rant
>>
>>
>> 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.
>
>
> You could search here instead <https://grafikrobot.github.io/b2doc/>.

By the way, plug [1], can it have a search box?

[1] https://lists.boost.org/boost-build/2018/03/29878.php


>> 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.
>> But, as long-time Boost.Build users, I dare to judge this is an
>> excellent example of why people hate this awesome build system :)
>
>
> "b2 headers" is an entirely Boost C++ Libraries specific construct and other
> than using b2 has nothing to do with b2 itself.

Fair.

The b2doc makes sense

"
target
    All tokens that are neither options nor properties specify what
targets to build.
"

Does it mean, it is guaranteed that single word in b2 command line
always means a target name?

And, as a target name, it is a thing specific to particular build configuration.

> The same applies to all the rest of that documentation you just pointed out :-)
> And hence why it's not in the b2 documentation.
> Hence what you are actually saying is that people
> hate the Boost C++ Libraries setup and not b2. And I don't blame them.. I
> don't like it either ;-) Which is why I've been working to put as much
> distance between Boost C++ Libraries and b2.

I'm greatful for your efforts!

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
On 9 April 2018 at 18:49, Mateusz Loskot <[hidden email]> wrote:

> On 9 April 2018 at 16:09, Rene Rivera <[hidden email]> wrote:
>> On Mon, Apr 9, 2018 at 8:35 AM, Mateusz Loskot <[hidden email]> wrote:
>>>
>>> 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.
>>> But, as long-time Boost.Build users, I dare to judge this is an
>>> excellent example of why people hate this awesome build system :)
>>
>>
>> "b2 headers" is an entirely Boost C++ Libraries specific construct and other
>> than using b2 has nothing to do with b2 itself.
>
> Fair.
>
> The b2doc makes sense
>
> "
> target
>     All tokens that are neither options nor properties specify what
> targets to build.
> "

b2 --toolset=gcc-5

This works as expected, of course, and does it work due to this rule?

"
properties
   (...) Syntactically, all command line tokens with an equal sign in
them are considered to specify properties.
"

IOW, equal sign has higher priority, and -- is discarded, so it is a
property, not an option. Correct?

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
AMDG

On 04/09/2018 10:59 AM, Mateusz Loskot via Boost-build wrote:

> On 9 April 2018 at 18:49, Mateusz Loskot <[hidden email]> wrote:
>> On 9 April 2018 at 16:09, Rene Rivera <[hidden email]> wrote:
>>>>> "
>> target
>>     All tokens that are neither options nor properties specify what
>> targets to build.
>> "
>
> b2 --toolset=gcc-5
>
> This works as expected, of course, and does it work due to this rule?
>
> "
> properties
>    (...) Syntactically, all command line tokens with an equal sign in
> them are considered to specify properties.
> "
>
> IOW, equal sign has higher priority, and -- is discarded, so it is a
> property, not an option. Correct?
>

  No.  -- takes priority.  --toolset is a special case which
exists for backwards compatibility and is discouraged.

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
AMDG

On 04/09/2018 07:35 AM, Mateusz Loskot via Boost-build wrote:

> Hi,
>
> TL;TR: A rant
>
>
> 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.  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.

  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.

> But, as long-time Boost.Build users, I dare to judge this is an
> excellent example of why peole hate this awesome build system :)
>

In Christ,
Steven Watanabe
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
On 4/9/18 10:27 AM, Steven Watanabe via Boost-build wrote:
> AMDG

>    `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.  As a result, the obvious
> places to put this documentation (the getting started
> guide and `b2 --help` from $BOOST_ROOT) are not really
> correct.

LOL - THIS end user uses github from my machine.  I invoke b2 headers as
needed.

OK - you're going to argue that I'm not a typical end user.  I don't kno
about that.  But this is a great way of working.  We should encourage
users to connect to github directly.  The idea of downloading a huge
monolithic boost distribution on from time to so last century.

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

Hmmm  - I never trusted that, but if you say so ...
>
>> But, as long-time Boost.Build users, I dare to judge this is an
>> excellent example of why peole hate this awesome build system :)

Right - unfortunately you're not alone.

I think the build system lacks clarity regarding whom it is trying to
serve, what it's proper scope is and what it is supposed to do.

Robert Ramey

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 9 April 2018 at 19:27, Steven Watanabe via Boost-build
<[hidden email]> 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
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 9 April 2018 at 19:40, Robert Ramey via Boost-build
<[hidden email]> wrote:
> On 4/9/18 10:27 AM, Steven Watanabe via Boost-build wrote:
>
> OK - you're going to argue that I'm not a typical end user.  I don't kno
> about that.  But this is a great way of working.  We should encourage users
> to connect to github directly.  The idea of downloading a huge monolithic
> boost distribution on from time to so last century.

That's why I've been prototyping CMake configuration for Boost.GIL that
should allow contributors to use reasonably new Boost installed system-wide
from binary distribution, then `git pull boostorg/gil` only and
be able to develop.

>>> But, as long-time Boost.Build users, I dare to judge this is an
>>> excellent example of why peole hate this awesome build system :)
>
> I think the build system lacks clarity regarding whom it is trying to serve,
> what it's proper scope is and what it is supposed to do.

Might be. TBH, I'm not able to clarify myself what bit of the docs
belongs to where.

However, using CMake-based knowledge,
for general CMake options I go to cmake.org/docs;
for a project specific build options, I refer to project.org/docs.
But, I know that the former start with CMAKE_ prefix and that small
detail is extremely important to get my bearings right.

I see no conventions or patterns, no no-brainers to learn.

Why not allow intrinsic b2 properties as options

b2 --toolset=gcc --variant=debug

while all project/configuration-specific can only be given as

b2 --property foo=bar
b2 -p foo=bar

or something like that.

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
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
> <[hidden email]> 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
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
On 9 April 2018 at 21:43, Steven Watanabe via Boost-build
<[hidden email]> 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 <[hidden email]> 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
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: [doc] b2 headers

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 9 April 2018 at 15:35, Mateusz Loskot <[hidden email]> wrote:

>
> TL;TR: A rant
>
>
> I've been looking for documentation about purpose of command
>
> b2 headers
>
> [...]
> 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.


FYI, I've taken the liberty to update the wiki [1] based on the above.

[1] https://github.com/boostorg/boost/wiki/Getting-Started

--
Mateusz Loskot, http://mateusz.loskot.net
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build