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

From: Edward Diener (eldiener_at_[hidden])
Date: 2020-09-22 16:59:36

On 9/22/2020 12:47 PM, Mateusz Loskot via Boost wrote:
> 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.

Using "required" is probably a pretty bad word. Something else might be 
better. I am not hung up on terminology, but some word that tells the 
end-user that with some higher C++ level(s) more functionality is 
available in the library I think would also be useful. Of course this 
information is probably available somewhere in the docs, if you can find 
it. If my original "extended" and/or "required" is dropped that is fine 
with me, but let's at least give the end-user the immediate knowledge of 
what C++ minimum level is needed to use a Boost library. Having read 
through enough Boost library docs I know that information is often not 
provided at all and, if it is there, is hard to find.