Re: Proposal for adding C++ level to the meta/libraries.json

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2020-09-22 16:47:12

On Tue, 22 Sep 2020 at 18:03, Edward Diener via Boost <boost_at_[hidden]>
wrote:

> On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:
> >> -----Original Message-----
> >> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Edward Diener
> via Boost
> >> Sent: 21 September 2020 18:37
> >> To: boost_at_[hidden]
> >> Cc: Edward Diener <eldiener_at_[hidden]>
> >> Subject: [boost] Proposal for adding C++ level to the
> meta/libraries.json
> >>
> >> Since we are reviewing Vinnie Falco's JSON library I thought that this
> would be a good time to present a
> >> proposal to add information to each Boost library's meta/libraries.json
> file regarding the level of C++
> >> standard compliance for that library. This could then be added to each
> library's visual documentation so
> >> that end-users would instantly know the C++ standard level they would
> need to use in order to use a
> >> Boost library.
> >>
> >> My proposal is to add 3 fields whose data would be the same as the
> cxxstd allowed values from Boost
> >> Build, using the first value of each choice ( currently 03, 11, 14, 17,
> 20 ).
> >>
> >> standard = minimum C++ level for the library extended = same
> functionality in the library as the
> >> minimum C++ level but with extended use given higher C++ levels
> required = new functionality in the
> >> library above the minimum C++ level which requires given higher C++
> levels
> >>
> >> The 'standard' field would be a single value, while the 'extended' or
> 'required' fields could be more than
> >> one comma separated value. If you don't like the names for 'standard',
> 'extended', or 'required' you can
> >> bikeshed the name, although I think the 'standard' name is pretty well
> apparent.
> >>
> >> The idea is to provide this information in the meta/libraries.json
> field for each library, so that the end-
> >> user of the library can immediately know the usability of the library
> with appropriate C++ standard
> >> levels of compilation.
> >>
> >> I realize that the line between the 'extended' and 'required' entries,
> as I have described them, could be
> >> blurred. The 'standard' field remains the most important. I have long
> felt that the end-user should not
> >> have to do any investigation, in code or in documentation, just to
> determine if a library is usable for his
> >> C++ standard level of compilation.
> >
> > I've been muttering about this tricky issue for some time.
> >
> > For a big and old and still growing library like Boost.Math, the problem
> is even more difficult.
> >
> > For many math functions and distributions, C++03 (with C++11
> numeric_limits) is fine, but as one starts to use newer items, then
> requirement shift up to needing C++20.
> >
> > We have recently decided to require a minimum C++11, but that still
> means that users may find that some components need more.
> >
> > Predicting the requirements for certain is difficult -  I fear in
> practice, it means 'sucking and seeing' ☹
> >
> > I have suggested marking each header file with its minimum requirements,
> but that is messy and doesn't really help the user much.
> >
> > My ideal is to say 'always use the latest compiler version and highest
> standard level', but that isn't popular 😉
> >
> > But it is a reason to encourage users to plan to keep updating all their
> tools - and keep their management on-board with that concept.
> >
> > So I support Edward's proposal, but caution that it isn't as helpful for
> some libraries as others.
>
> You could tag Math as:
>
> standard : 11
> required : 14, 17, 20
>
> It least that tells end-users that C++11 is the minimum level but that
> some functionality will need C++14, C++17, or C++20.
>

I see the idea better now.

Well, trying to put myself in a library users' shoes,
seeing `required : 14, 17, 20` raises more questions.

I'd rather appreciate to see `required: 11`,
then read a section in the docs explaining that
"if BOOST_MATH_FANCY_X is defined, then C++14 is required;
if <x> is included, then C++17 is required"
and other details clearly, as a guide,
less obscure than list of numbers.

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