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

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

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

Boost - Dev mailing list
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.


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

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

Boost - Dev mailing list
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.

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

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

Boost - Dev mailing list
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.)


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

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

Boost - Dev mailing list
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.


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

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

Boost - Dev mailing list
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

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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list


> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Edward Diener via Boost
> Sent: 21 September 2020 18:37
> To: [hidden email]
> Cc: Edward Diener <[hidden email]>
> 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


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

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

Boost - Dev mailing list

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

>> -----Original Message-----
>> From: Boost <[hidden email]> On Behalf Of Edward Diener via Boost
>> Sent: 21 September 2020 18:37
>> To: [hidden email]
>> Cc: Edward Diener <[hidden email]>
>> 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




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

smime.p7s (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Mon, 21 Sep 2020 at 19:38, Edward Diener via Boost
<[hidden email]> 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

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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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).

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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:

>
>
>> -----Original Message-----
>> From: Boost <[hidden email]> On Behalf Of Edward Diener via Boost
>> Sent: 21 September 2020 18:37
>> To: [hidden email]
>> Cc: Edward Diener <[hidden email]>
>> 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."
>



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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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 ).


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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 9/22/2020 7:03 AM, Mateusz Loskot via Boost wrote:

> On Mon, 21 Sep 2020 at 19:38, Edward Diener via Boost
> <[hidden email]> 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


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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Tue, 22 Sep 2020 at 18:03, Edward Diener via Boost <[hidden email]>
wrote:

> On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:
> >> -----Original Message-----
> >> From: Boost <[hidden email]> On Behalf Of Edward Diener
> via Boost
> >> Sent: 21 September 2020 18:37
> >> To: [hidden email]
> >> Cc: Edward Diener <[hidden email]>
> >> 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

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

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

Boost - Dev mailing list
On 9/22/2020 12:47 PM, Mateusz Loskot via Boost wrote:

> On Tue, 22 Sep 2020 at 18:03, Edward Diener via Boost <[hidden email]>
> wrote:
>
>> On 9/22/2020 4:42 AM, Paul A Bristow via Boost wrote:
>>>> -----Original Message-----
>>>> From: Boost <[hidden email]> On Behalf Of Edward Diener
>> via Boost
>>>> Sent: 21 September 2020 18:37
>>>> To: [hidden email]
>>>> Cc: Edward Diener <[hidden email]>
>>>> 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.


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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list


> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Edward Diener via Boost
> Sent: 22 September 2020 17:03
> To: [hidden email]
> Cc: Edward Diener <[hidden email]>
> 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 <[hidden email]> On Behalf Of Edward
> >> Diener via Boost
> >> Sent: 21 September 2020 18:37
> >> To: [hidden email]
> >> Cc: Edward Diener <[hidden email]>
> >> 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



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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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

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

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

Boost - Dev mailing list

> On 23. Sep 2020, at 08:54, Spencer Collyer via Boost <[hidden email]> 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.

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

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

Boost - Dev mailing list


> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Hans Dembinski via Boost
> Sent: 23 September 2020 08:53
> To: Boost Devs <[hidden email]>
> Cc: Hans Dembinski <[hidden email]>
> Subject: Re: [boost] Proposal for adding C++ level to the meta/libraries.json
>
>
> > On 23. Sep 2020, at 08:54, Spencer Collyer via Boost <[hidden email]> 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/boost_macro_reference.html

and how to use them

https://www.boost.org/doc/libs/1_74_0/libs/config/doc/html/boost_config/build_config.html

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




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

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

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> Gesendet: Mittwoch, 23. September 2020 um 09:53 Uhr
> Von: "Hans Dembinski via Boost" <[hidden email]>
>
> > On 23. Sep 2020, at 08:54, Spencer Collyer via Boost <[hidden email]> 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
>

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

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

Boost - Dev mailing list
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.


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