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

newer
[review][JSON] The library name...

Edward Diener

21 Sep 2020 21 Sep '20

5:37 p.m.

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.

Show replies by date

Gavin Lambert

22 Sep 22 Sep

1:41 a.m.

On 22/09/2020 05:37, Edward Diener wrote:

...

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

There's already a "std": [ "tr1"/"proposal" ] field, perhaps this should be extended rather than replaced? While undocumented, I note some libraries have already made use of this as std: [ "c++17" ] for example.

Peter Dimov

2 a.m.

Gavin Lambert wrote:

...

There's already a "std": [ "tr1"/"proposal" ] field, perhaps this should be extended rather than replaced?

While undocumented, I note some libraries have already made use of this as std: [ "c++17" ] for example.

"std" actually means something different: which C++ standard contains the library. (E.g. boost::bind is in C++11, boost::optional is in C++17.)

Edward Diener

3:17 a.m.

On 9/21/2020 10:00 PM, Peter Dimov via Boost wrote:

...

Gavin Lambert wrote:

...
There's already a "std": [ "tr1"/"proposal" ] field, perhaps this should be extended rather than replaced?

While undocumented, I note some libraries have already made use of this as std: [ "c++17" ] for example.

"std" actually means something different: which C++ standard contains the library. (E.g. boost::bind is in C++11, boost::optional is in C++17.)

Right ! My suggested field can be renamed, let's say, "mode" instead of "standard", so as not to be confused with "std" if people like that. In fact I do not care what names are given to my three categories, but I think the categories themselves are valid and useful. Really C++ programmers should not have to delve into a library in some unknown way just to find if they can use a library, when they compile their code at some C++ level. Why are we making it hard in Boost for programmers to find out that sort of basic and useful information, rather than just document that information in some common place. Since all Boost libraries have this meta information, documenting it there would be both common and useful. Credit goes not to me but to whoever pushed forward the idea of using the meta/libraries.json file for meta-like information. I am just suggesting a useful reason for using some meta information that I am sure would benefit programmers using Boost libraries.

Glen Fernandes

3:24 a.m.

On Mon, Sep 21, 2020 at 11:17 PM Edward Diener wrote:

...

Really C++ programmers should not have to delve into a library in some unknown way just to find if they can use a library, when they compile their code at some C++ level. Why are we making it hard in Boost for programmers to find out that sort of basic and useful information, rather than just document that information in some common place. Since all Boost libraries have this meta information, documenting it there would be both common and useful.

Agreed. It will be useful to at least show the minimum C++ standard version that a library targets.

...

Credit goes not to me but to whoever pushed forward the idea of using the meta/libraries.json file for meta-like information.

Since you will be the one implementing this feature in the website, credit will go to you too. Glen

pbristow＠hetp.u-net.com

8:42 a.m.

...

-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener 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. The bottom line is always going to be: "If it works for your configuration, fine - otherwise bad luck." Paul

Alexander Grund

10:22 a.m.

Am 22.09.20 um 10:42 schrieb Paul A Bristow via Boost:

...

...
-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener 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.

TBH I didn't understand the meaning of "extended" and "required" as I failed to parse the sentence. Might be my English though. How about: - minimum required C++ standard version to use this library - maximum C++ standard version which adds new features (i.e. for Math that would be C++20, although for most libs it would be the same as above) - opt.: Superseded by which C++ standard version (this came up in the "deprecate C++03" discussions): When a library has been fully (or mostly) absorbed by a standard that might be valuable to tell) I think the first is unquestionable and easiest. The latter 2 are optional and could be harder to specify and keep up to date. But at least there is a clear distinction what is what

Edward Diener

4:02 p.m.

On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:

...

...
-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener 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 think that information is very helpful to end-users. Nothing is perfect but let's settle for what is at least good and helpful.

...

The bottom line is always going to be: "If it works for your configuration, fine - otherwise bad luck."

Mateusz Loskot

4:47 p.m.

On Tue, 22 Sep 2020 at 18:03, Edward Diener via Boost wrote:

...

...
...
-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener Subject: [boost] Proposal for adding C++ level to the

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

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

On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote: meta/libraries.json library's visual documentation so 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

Edward Diener

4:59 p.m.

On 9/22/2020 12:47 PM, Mateusz Loskot via Boost wrote:

...

On Tue, 22 Sep 2020 at 18:03, Edward Diener via Boost wrote:

...
...
...
-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener Subject: [boost] Proposal for adding C++ level to the

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

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

On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote: meta/libraries.json library's visual documentation so 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.

Spencer Collyer

23 Sep 23 Sep

6:54 a.m.

On Tue, 22 Sep 2020 12:59:36 -0400, Edward Diener via Boost wrote:

...

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

Seeing 'required' followed by a list of versions is confusing - you can imagine a user thinking 'well does it require C++20 to use, and if so why mention the earlier versions'. Maybe use 'enhanced' (or 'enhanced_by') rather than 'required'. Or 'added_value'? Spencer

Hans Dembinski

7:53 a.m.

...

On 23. Sep 2020, at 08:54, Spencer Collyer via Boost wrote:

Maybe use 'enhanced' (or 'enhanced_by') rather than 'required'. Or 'added_value'?

+1 for 'enhanced'. Apart from the minimum, it is useful for lib authors to advertise that they support newer standards as well.

pbristow＠hetp.u-net.com

8:38 a.m.

...

-----Original Message----- From: Boost On Behalf Of Hans Dembinski via Boost Sent: 23 September 2020 08:53 To: Boost Devs Cc: Hans Dembinski Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json

...
On 23. Sep 2020, at 08:54, Spencer Collyer via Boost wrote:

Maybe use 'enhanced' (or 'enhanced_by') rather than 'required'. Or 'added_value'?

+1 for 'enhanced'.

I'm not sure about 'enhanced'. What the metadata is saying is 'some library features require up to C++20'. Why not just give a *range of requirements* for example: "C++11 to C++17"? Of course what would be much more helpful, but a massive lot more work would be to list the requirements in Boost-style descriptors, for example, cxx11_lambdas cxx11_auto_declarations ... These are derived from https://www.boost.org/doc/libs/1_74_0/libs/config/doc/html/boost_config/boos... and how to use them https://www.boost.org/doc/libs/1_74_0/libs/config/doc/html/boost_config/buil... For example a line from \boost\libs\math\test\Jamfile.v2 noting the 'requires' [ run test_1F0.cpp ../../test/build//boost_unit_test_framework : : : [ requires cxx11_auto_declarations cxx11_lambdas cxx11_unified_initialization_syntax cxx11_smart_ptr ] ] # hypergeometric_pFq_checked_series.hpp uses auto, the rest are from quadrature tests. We might consider adding these requirement to the JSON metadata, but when they vary from library sub-feature like function, it would be duplicating what can be deduced from consulting the tests in jamfiles. (And more work than I feel is worthwhile). Paul PS

...

Apart from the minimum, it is useful for lib authors to advertise that they support newer standards as well.

Don't we always expect (well - hope for) a C++03 library to still work with C++20? (It might take a BOOST_ macro to hide differences).

Hans Dembinski

9:29 a.m.

...

On 23. Sep 2020, at 10:38, Paul A Bristow via Boost wrote:

Don't we always expect (well - hope for) a C++03 library to still work with C++20?

(It might take a BOOST_ macro to hide differences).

It is more than that. A library may add support for hand-crafted deduction guides on a C++17 compiler, for example (as in case of Boost.Histogram).

Rainer Deyke

11:15 a.m.

On 23.09.20 10:38, Paul A Bristow via Boost wrote:

...

Why not just give a *range of requirements* for example: "C++11 to C++17"?

To me, that reads as "the library does not with C++20" or "the library is rendered obsolete by C++20", not "the library has no features that C++20". I'm actually very interested in when a library is rendered obsolete by a C++ standard. Lots of Boost libraries have equivalents in the C++ standard library, or in some cases in the language itself. In some cases, the standard library component has completely rendered the Boost version obsolete. In some cases, the Boost version only exists as a backport of the standard library component, and was never intended to be used in C++ versions that include that component. In some cases, the Boost version and the standard library component have developed in different directions, and both are viable. And in some cases, the Boost version exists to correct a perceived flaw in a standard library component, so the Boost version should probably be preferred. It is often not clear which of these applies to which library, even after reading the library documentation (which may predate the standard library component). Some examples: - Boost.Assign looks like it has been rendered obsolete by std::initializer_list, but maybe it still has some functionality that std::initializer_list cannot handle? - Boost.Atomic: the short library description "C++11-style atomic<>" implies a backport of C++11 functionality to C++03, but I don't know if that's actually the case. - Boost.Variant[2]: I know that Boost.Variant predates std::variant, which in turn predates boost::variant2, but neither of these libraries provides a simple and clear explanation of how it differs from std::variant. -- Rainer Deyke (rainerd@eldwood.com)

pbristow＠hetp.u-net.com

3:42 p.m.

...

-----Original Message----- From: Boost On Behalf Of Rainer Deyke via Boost Sent: 23 September 2020 12:16 To: boost@lists.boost.org Cc: Rainer Deyke Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json

On 23.09.20 10:38, Paul A Bristow via Boost wrote:

...
Why not just give a *range of requirements* for example: "C++11 to C++17"?

To me, that reads as "the library does not with C++20" or "the library is rendered obsolete by C++20", not "the library has no features that C++20".

OK - I see the scope for confusion. How about A *range of MINIMUM requirements* for example: "C++11 to C++17"?

...

I'm actually very interested in when a library is rendered obsolete by a C++ standard. Lots of Boost libraries have equivalents in the C++ standard library, or in some cases in the language itself. In some cases, the standard library component has completely rendered the Boost version obsolete. In some cases, the Boost version only exists as a backport of the standard library component, and was never intended to be used in C++ versions that include that component. In some cases, the Boost version and the standard library component have developed in different directions, and both are viable. And in some cases, the Boost version exists to correct a perceived flaw in a standard library component, so the Boost version should probably be preferred. It is often not clear which of these applies to which library, even after reading the library documentation (which may predate the standard library component).

Some examples: - Boost.Assign looks like it has been rendered obsolete by std::initializer_list, but maybe it still has some functionality that std::initializer_list cannot handle? - Boost.Atomic: the short library description "C++11-style atomic<>" implies a backport of C++11 functionality to C++03, but I don't know if that's actually the case. - Boost.Variant[2]: I know that Boost.Variant predates std::variant, which in turn predates boost::variant2, but neither of these libraries provides a simple and clear explanation of how it differs from std::variant.

Doesn't (or shouldn't) all Boost libraries just redirect to use the standard library when appropriate (without loss of features)? This allows continued use by unfortunates stuck with VS 6 as well the luckier VS latest trackers. I see this as a Boost USP. Paul

Peter Dimov

4:12 p.m.

...

...
- Boost.Variant[2]: I know that Boost.Variant predates std::variant, which in turn predates boost::variant2, but neither of these libraries provides a simple and clear explanation of how it differs from std::variant.

Wait what https://www.boost.org/doc/libs/1_74_0/libs/variant2/doc/html/variant2.html#d...

Rainer Deyke

24 Sep 24 Sep

5:10 a.m.

On 23.09.20 18:12, Peter Dimov via Boost wrote:

...

...
...
- Boost.Variant[2]: I know that Boost.Variant predates std::variant, > which in turn predates boost::variant2, but neither of these libraries > provides a simple and clear explanation of how it differs from > std::variant.

Wait what

https://www.boost.org/doc/libs/1_74_0/libs/variant2/doc/html/variant2.html#d...

I don't know how I missed that. It's not at the top of the documentation, but it's definitely there, and I should have seen it. -- Rainer Deyke (rainerd@eldwood.com)

Gavin Lambert

2:57 a.m.

On 23/09/2020 23:15, Rainer Deyke wrote:

...

I'm actually very interested in when a library is rendered obsolete by a C++ standard. Lots of Boost libraries have equivalents in the C++ standard library, or in some cases in the language itself. In some cases, the standard library component has completely rendered the Boost version obsolete. In some cases, the Boost version only exists as a backport of the standard library component, and was never intended to be used in C++ versions that include that component. In some cases, the Boost version and the standard library component have developed in different directions, and both are viable. And in some cases, the Boost version exists to correct a perceived flaw in a standard library component, so the Boost version should probably be preferred. It is often not clear which of these applies to which library, even after reading the library documentation (which may predate the standard library component).

In theory, I think that's what the existing "std" field was for: "this library is included in this standard version". Although that's not the whole story, since e.g. Boost.Assign as you mentioned was not directly included but (AFAIK) is rendered entirely obsolete by initializer lists, and e.g. Boost.SmartPtr and Boost.Thread while *mostly* obsolete do include some extended functionality not in the standard implementation. And Boost.Variant[2] make different design choices from the standard implementation, so all three are viable alternatives. I don't think any meta field is really going to capture these sorts of things too well.

pbristow＠hetp.u-net.com

8:59 a.m.

...

-----Original Message----- From: Boost On Behalf Of Gavin Lambert via Boost Sent: 24 September 2020 03:57 To: boost@lists.boost.org Cc: Gavin Lambert Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json

On 23/09/2020 23:15, Rainer Deyke wrote:

...
I'm actually very interested in when a library is rendered obsolete by a C++ standard. Lots of Boost libraries have equivalents in the C++ standard library, or in some cases in the language itself. In some cases, the standard library component has completely rendered the Boost version obsolete. In some cases, the Boost version only exists as a backport of the standard library component, and was never intended to be used in C++ versions that include that component. In some cases, the Boost version and the standard library component have developed in different directions, and both are viable. And in some cases, the Boost version exists to correct a perceived flaw in a standard library component, so the Boost version should probably be preferred. It is often not clear which of these applies to which library, even after reading the library documentation (which may predate the standard library component).

In theory, I think that's what the existing "std" field was for: "this library is included in this standard version".

Although that's not the whole story, since e.g. Boost.Assign as you mentioned was not directly included but (AFAIK) is rendered entirely obsolete by initializer lists, and e.g. Boost.SmartPtr and Boost.Thread while *mostly* obsolete do include some extended functionality not in the standard implementation.

And Boost.Variant[2] make different design choices from the standard implementation, so all three are viable alternatives.

I don't think any meta field is really going to capture these sorts of things too well.

But better than nothing? Provided we don't oversell the information. We need some BIG cautions that this is only a very approximate guide to the full story - which is ultimately "try it and see". Paul

Edward Diener

10:36 a.m.

On 9/24/2020 4:59 AM, Paul A Bristow via Boost wrote:

...

...
-----Original Message----- From: Boost On Behalf Of Gavin Lambert via Boost Sent: 24 September 2020 03:57 To: boost@lists.boost.org Cc: Gavin Lambert Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json

On 23/09/2020 23:15, Rainer Deyke wrote:

...
I'm actually very interested in when a library is rendered obsolete by a C++ standard. Lots of Boost libraries have equivalents in the C++ standard library, or in some cases in the language itself. In some cases, the standard library component has completely rendered the Boost version obsolete. In some cases, the Boost version only exists as a backport of the standard library component, and was never intended to be used in C++ versions that include that component. In some cases, the Boost version and the standard library component have developed in different directions, and both are viable. And in some cases, the Boost version exists to correct a perceived flaw in a standard library component, so the Boost version should probably be preferred. It is often not clear which of these applies to which library, even after reading the library documentation (which may predate the standard library component).

In theory, I think that's what the existing "std" field was for: "this library is included in this standard version".

Although that's not the whole story, since e.g. Boost.Assign as you mentioned was not directly included but (AFAIK) is rendered entirely obsolete by initializer lists, and e.g. Boost.SmartPtr and Boost.Thread while *mostly* obsolete do include some extended functionality not in the standard implementation.

And Boost.Variant[2] make different design choices from the standard implementation, so all three are viable alternatives.

I don't think any meta field is really going to capture these sorts of things too well.

But better than nothing?

Provided we don't oversell the information. We need some BIG cautions that this is only a very approximate guide to the full story - which is ultimately "try it and see".

My disgust with the "try it and see" approach is the main reason why I proposed the additions to the meta information, which would, at the very least, tell the end-user whether a Boost library is compilable for the C++ standard level they are using. Is this really too much information to give end-users, and is it really better that an end-user should have to dig through Boost library docs, where the information is often not there at all even if it could be found, just to find out if Boost library X can be compiled by the end-user who is using C++ standard level Y for his project ? I doubt it. Yes, a given library might be more complicated, and provide some functionality over and above the minimal C++ standard level needed to use that library depending on a host of features in the compiler being used, but that is no reason to not at least tell the end-user what the minimum level needed actually is, and then the end-user can read the docs and hopefully find out what other "advanced" library features, needing what other C++ standard level features, are available for that library. But that does not negate the fact that simply using the basic features of a Boost library the end-user would like to know if his C++ standard compilation level is good enough for X library's main functionality.

Mike

23 Sep 23 Sep

9:03 a.m.

...

Gesendet: Mittwoch, 23. September 2020 um 09:53 Uhr Von: "Hans Dembinski via Boost"

...
On 23. Sep 2020, at 08:54, Spencer Collyer via Boost wrote:

Maybe use 'enhanced' (or 'enhanced_by') rather than 'required'. Or 'added_value'?

+1 for 'enhanced'. Apart from the minimum, it is useful for lib authors to advertise that they support newer standards as well.

Please keep it simple: The minimum required standard has an immediate value for tooling and is easily understood by the user: "If you want to use the library, you have to enable that mode" / "If my toolchain only supports c++XX, I should not try to build/use this lib". Enhanced on the other hand doesn't tell me anything, except probably that there is at least one macro/precompilation branch that evaluates differently in different modes. Is a library already enhanced in c++14, if more functions become constexpr? Does a lib that is enhanced_by c++17 have to provide overloads for std::string_view? Is a library enhanced by c++XX, if the interface/cababilities remain the same, but the implementation is more efficient/needs fewer boost-internal dependencies? What about libs that use another lib that is enhanced by c++XX, but the lib itself doesn't care directly? Would boost config count as enhanced? Imho, "enhanced_by" is only useful when accompanied by further information detailing, what changes, so I'd keep that information in the readme/documentation. Also - as far as advertising is concerned - it is not like I (as human) am usually looking at meta at all, if I want to know something about a library. I'm looking at the readme and the documentation - of course that last point might be specific to myself and not representative. best Mike

...

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Peter Dimov

9:21 a.m.

Mike wrote:

...

Also - as far as advertising is concerned - it is not like I (as human) am usually looking at meta at all, if I want to know something about a library.

meta/libraries.json is not for humans, it's used to generate the library page. E.g. https://www.boost.org/doc/libs/1_74_0/ I think that we could just repurpose the "std" field, as it's not of much relevance now. Although "required" and "enhanced" work too.

pbristow＠hetp.u-net.com

22 Sep 22 Sep

5:04 p.m.

...

-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 22 September 2020 17:03 To: boost@lists.boost.org Cc: Edward Diener Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json

On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:

...
...
-----Original Message----- From: Boost On Behalf Of Edward Diener via Boost Sent: 21 September 2020 18:37 To: boost@lists.boost.org Cc: Edward Diener 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 think that information is very helpful to end-users. Nothing is perfect but let's settle for what is at least good and helpful.

OK - I'm happy with that - but it isn't a big help for some libraries.

...

...
The bottom line is always going to be: "If it works for your configuration, fine - otherwise bad luck."

Paul

Mateusz Loskot

11:03 a.m.

On Mon, 21 Sep 2020 at 19:38, Edward Diener via Boost wrote:

...

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

I once looked [1] for ways to specify minimum required version of C++ in the meta/libraries.json and I'm glad the idea is picking up an interest. But, do we really need such a detailed set of tags? We have `std`, as Peter pointed out. Why not just accompany it with `std_required` and display it in the libraries list in the docs. That's all the majority of users/developers need to know really. Any extra info on correspondence between a library and C++ standard can be easily explained in a brief section in the library's docs. [1] https://lists.boost.org/Archives/boost/2019/11/247385.php Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

Edward Diener

4:16 p.m.

On 9/22/2020 7:03 AM, Mateusz Loskot via Boost wrote:

...

On Mon, 21 Sep 2020 at 19:38, Edward Diener via Boost wrote:

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

I once looked [1] for ways to specify minimum required version of C++ in the meta/libraries.json and I'm glad the idea is picking up an interest.

But, do we really need such a detailed set of tags?

I am fine dropping the other two tags if that is what people want. I just thought they might be useful.

...

We have `std`, as Peter pointed out. Why not just accompany it with `std_required` and display it in the libraries list in the docs. That's all the majority of users/developers need to know really.

Any extra info on correspondence between a library and C++ standard can be easily explained in a brief section in the library's docs.

[1] https://lists.boost.org/Archives/boost/2019/11/247385.php

Andrey Semashev

2:35 p.m.

On 9/21/20 8:37 PM, Edward Diener via Boost wrote:

...

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.

One downside of a manual markup is that this information can go out of sync. Including due to changes in a dependency of a library. Granted, the status quo also has this downside, so it doesn't make things worse. But since we're talking about a tag in a JSON document, it would be nice if the value could be deduced from dependencies.

...

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'm not sure I understand what "extended" and "required" tags mean. I think the most practical tags are the minimal C++ version at which the library is minimally useful, and the minimal C++ version at which it is fully useful (meaning, the user can use all features of the library).

Edward Diener

4:14 p.m.

On 9/22/2020 10:35 AM, Andrey Semashev via Boost wrote:

...

On 9/21/20 8:37 PM, Edward Diener via Boost wrote:

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

One downside of a manual markup is that this information can go out of sync. Including due to changes in a dependency of a library. Granted, the status quo also has this downside, so it doesn't make things worse. But since we're talking about a tag in a JSON document, it would be nice if the value could be deduced from dependencies.

...
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'm not sure I understand what "extended" and "required" tags mean. I think the most practical tags are the minimal C++ version at which the library is minimally useful, and the minimal C++ version at which it is fully useful (meaning, the user can use all features of the library).

I proposed "extended" to mean that the C++ level(s) gives an easier means to use the functionality of the library without changing the functionality offered, while "required" is meant to mean that the C++ level(s) adds new functionality to the library. The former might be used if their was better, improved syntax in the library to use the functionality in the library above the minimum "standard" level, while "required" meant that added functionality exists in the library which is not available at the minimum "standard" level. If the two latter "extended" or "required" are dropped, I am fine with that, but let's at least tell the end-user what the minimum C++ level is to use a Boost library in an easy to find transparent way with "standard" ( or whatever you want to call it ).

1508

Age (days ago)

1511

Last active (days ago)

List overview

Download

27 comments

12 participants

participants (12)

Alexander Grund
Andrey Semashev
Edward Diener
Gavin Lambert
Glen Fernandes
Hans Dembinski
Mateusz Loskot
Mike
pbristow＠hetp.u-net.com
Peter Dimov
Rainer Deyke
Spencer Collyer