Boost logo

Boost :

Subject: Re: [boost] Enabling spectre mitigation in boost libraries
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2019-04-07 05:53:58

On Sat, Apr 6, 2019 at 11:23 PM Robert Ramey via Boost <
boost_at_[hidden]> wrote:

> On 4/6/19 7:22 PM, Rene Rivera via Boost wrote:
> >
> > These are not options pertaining to B2 itself. And hence have no mention
> in
> > the B2 documentation. You can see the options by doing:
> >
> > $ cd boost-root
> > $ b2 --help
> >
> > There are numerous install and build directory options listed in that.
> Use
> > the appropriate one. For the tagging there's a concept of "buildid" for
> > which there are two options present. The appropriate place to document
> > these in addition to the "--help" printout would be in the Getting
> Started
> > Boost pagesOr perhaps some other "Building Boost" documentation. Or
> > optionally the wiki. And it would seem that such "Case Study" examples
> > would lend themselves well to having on the wiki. Especially since it's
> > really, really, really, easy for everyone to contribute such
> documentation
> > through direct edit suggestion PRs to the wiki.
> >
> I think this view is very typical of library and tool developers. And I
> think it's a big problem.

TL;DR: You injected way more meaning into what I said. To the point of
mischaracterizing my intentions of simple declarative information.

a) Technically you're correct in that all the required information is
> available if one is willing to dig deep enough and invest some time. I
> think the time required is more than you think it is though.

Yes, I gave technical declarative information. I don't understand how you
ascertained anything past my technical statement.

> b) You frame task is building the software and the job of "spoon
> feeding" the user as beyond the developers responsibility and perhaps
> his ability.

I fixed the spelling mistake in that for you ;-)

c) I think you're dead wrong on this. Your task, should you choose to
> accept it, is to create something that lots of people will use and will
> spread.

Yes, what I chose to create was "Boost Build" and "Boost Predef".

> d) So, if the task isn't accomplished, the developer isn't done. He's
> failed to complete the required task.

Correct, I'm not done.

e) So this means putting the document on par with the code. The code
> programs the machine, and the document programs the user. If one
> doesn't work - nothing works.

Yep, I continually work on documentation improvements. For example spending
a year converting Boost Build documentation to a format that was a
magnitude easier for myself and others to contribute to. Which has worked
splendidly as we've gotten a handful of outside contributions in both
general improvement and new features with accompanying documentation.

f) Defining the task in this way and approaching it accordingly will
> result in a work flow which shuttles bank and forth between code and
> document resulting in better and simpler versions of both. This is
> because when problems are discovered, we can fix it in the simplest
> place to fix it.

Right. Which is why Boost Build and Boost Predef Documentation is partially
embedded in the source code and is in a simple text format. As it makes
it's more likely to get updated and be accurate. And that has been proven
to work rather well as experience with it has shown.

I know you guys are tired of me preaching this repeatedly. I'm sorry
> about this.

I'm not tired of that. But let me clarify my original statement.. The
installation and buildid features of "Boost C++ Libraries" are not part of
"Boost Build" (B2). B2 implements a build system that provides supporting
mechanisms to those features but does not contain them itself. They are
properly features of "Boost C++ Libraries" only. As a concrete delineation
of that consider this github search <> for "buildid"
in the entirety of all the Boost libraries. You can observe that the places
where that is present are in the super-project and in Boost.Config. Hence
_not_ in Boost Build. As such, my original key point, that such
documentation belongs where it currently is. And perhaps, and almost
certainly, as additions to the "Getting Started" documentation. But also
that it could be added in the wiki where it is more amenable public
contribution. I did not at any time say that such documentation should not
be written.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams -

Boost list run by bdawes at, gregod at, cpdaniel at, john at