Libraries and C++ compliance
I would like to ask people who present new libraries to Boost, in whatever stages they are, to please specify in the documentation to the library and/or in messages regarding the library, what level of C++ compliance is needed to use the functionality of that library. This plea is not being directed at any particular current library being mentioned by anyone on the mailing list, but is a general plea regarding developers and their efforts. I realize it is a real pain that C++ as a language, and as it continues to evolve, has a number of popular levels of C++ compliance. This is largely because C++ is offered by a number of different vendors in a number of different supported releases, each particular implementation supporting a number of levels of C++ compliance and sometimes only partially supporting a particular level of C++ compliance. But given this sometimes difficult situation I do not see it as enough for library docs/information to simply say "this library supports some-vendor/some-release" because this is actually fairly meaningless to me when I know that "some-vendor/some-release" supports a number of levels of C++ compliance through some compiler parameter ( often -std=something ). Therefore docs/information of "the library supports "some-implementation" or "the library is compliant with "more than one level of C++ compliance" tells me as much as if some one told me that the moon is yellow. So I am begging, pleading, entreating library authors to be specific about the C++ features or the C++ level of compliance needed to use their library, even if it is just a one-liner that succinctly explains what the end-user needs to know. Furthermore, for any given library could we please have specific information about what will happen if I use the library, or some feature of the library, without the desired minimum level of C++ compliance. While I would assume compile-time compiler errors as the norm another possibility, especially given the excellent support in Boost Config to compiler conformance, are more readable preprocessor errors. Finally a library might offer some level of advanced C++ compliance but fall back to a lower level if possible. Please, please library authors this is important. No end-user or tester of your library wants to spend extended time trying to figure out why some compile fails when the answer turns out simply to be one of inadequate C++ conformance level for a particular compiler implementation being used with a particular level of conformance.
On 10/04/2017 03:24, Edward Diener via Boost wrote:
Please, please library authors this is important. No end-user or tester of your library wants to spend extended time trying to figure out why some compile fails when the answer turns out simply to be one of inadequate C++ conformance level for a particular compiler implementation being used with a particular level of conformance.
Outcome is up for review here end of May. Are you happy with its compiler support at https://ned14.github.io/boost.outcome/prerequisites.html? To save people clicking on the link: "Outcome is a header only C++ 14 library known to work on these compilers or better: clang 3.5 (LLVM) clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3 *A copy of Boost is not required to use this library. You can simply drop Outcome into your project and go.* Warning: MSVC generates significant code bloat when using Outcome in large code bases. If you can use VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables. Execution speed is not particularly different, though one would have thought the extra cache load caused by code bloat might affect some applications. In this situation, use LLVM clang targeting the MSVC ABI." Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 10 April 2017 08:05 To: boost@lists.boost.org Cc: Niall Douglas Subject: Re: [boost] Libraries and C++ compliance
On 10/04/2017 03:24, Edward Diener via Boost wrote:
Please, please library authors this is important. No end-user or tester of your library wants to spend extended time trying to figure out why some compile fails when the answer turns out simply to be one of inadequate C++ conformance level for a particular compiler implementation being used with a particular level of conformance.
+1 - this IS really important to users. (and even info on what happens with older versions that the author cannot test, including any clues. "Some parts will probably work with C++ 2003 but no tested." are also useful). Using BOOST_STATIC_ASSERT_MSG at the right places is really helpful too.
Outcome is up for review here end of May.
Are you happy with its compiler support at https://ned14.github.io/boost.outcome/prerequisites.html? To save people clicking on the link:
"Outcome is a header only C++ 14 library known to work on these compilers or better:
clang 3.5 (LLVM) clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3 <snip>
Yes - just right. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Mon, Apr 10, 2017 at 9:04 AM, Niall Douglas via Boost <boost@lists.boost.org> wrote:
Warning: MSVC generates significant code bloat when using Outcome in large code bases. If you can use VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables. Execution speed is not particularly different, though one would have thought the extra cache load caused by code bloat might affect some applications. In this situation, use LLVM clang targeting
What situation? VS2015?
the MSVC ABI."
-- Olaf
On 10/04/2017 10:09, Olaf van der Spek wrote:
On Mon, Apr 10, 2017 at 9:04 AM, Niall Douglas via Boost <boost@lists.boost.org> wrote:
Warning: MSVC generates significant code bloat when using Outcome in large code bases. If you can use VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables. Execution speed is not particularly different, though one would have thought the extra cache load caused by code bloat might affect some applications. In this situation, use LLVM clang targeting
What situation? VS2015?
the MSVC ABI."
Note the phrase "Warning: **MSVC** generates significant ..." Note the earlier mention that VS2015 Update 2 or later is known to work. This implies VS2015 Update 1 or earlier does not. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On Mon, Apr 10, 2017 at 3:20 PM, Niall Douglas via Boost <boost@lists.boost.org> wrote:
On 10/04/2017 10:09, Olaf van der Spek wrote:
On Mon, Apr 10, 2017 at 9:04 AM, Niall Douglas via Boost <boost@lists.boost.org> wrote:
Warning: MSVC generates significant code bloat when using Outcome in large code bases. If you can use VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables. Execution speed is not particularly different, though one would have thought the extra cache load caused by code bloat might affect some applications. In this situation, use LLVM clang targeting
What situation? VS2015?
the MSVC ABI."
Note the phrase "Warning: **MSVC** generates significant ..."
Note the earlier mention that VS2015 Update 2 or later is known to work. This implies VS2015 Update 1 or earlier does not.
Does it not work at all or does it do bloated code?
VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables.
This bit makes it sound VS2017 is required to avoid the code bloat. -- Olaf
On 11/04/2017 08:03, Olaf van der Spek wrote:
Warning: MSVC generates significant code bloat when using Outcome in large code bases. If you can use VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables. Execution speed is not particularly different, though one would have thought the extra cache load caused by code bloat might affect some applications. In this situation, use LLVM clang targeting
What situation? VS2015?
the MSVC ABI."
Note the phrase "Warning: **MSVC** generates significant ..."
Note the earlier mention that VS2015 Update 2 or later is known to work. This implies VS2015 Update 1 or earlier does not.
Does it not work at all or does it do bloated code?
What did the statement say? "Outcome is a header only C++ 14 library known to work on these compilers or better: clang 3.5 (LLVM) clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3" I cannot help if you don't read the text.
VS2017 which implements C++ 14 constexpr and has a better optimiser for modern C++, you will see tigher executables.
This bit makes it sound VS2017 is required to avoid the code bloat.
Exactly what the statement says. I don't see why we are discussing this? Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On 12/04/2017 00:37, Niall Douglas via Boost wrote:
On 11/04/2017 08:03, Olaf van der Spek wrote:
Does it not work at all or does it do bloated code?
What did the statement say?
"Outcome is a header only C++ 14 library known to work on these compilers or better:
clang 3.5 (LLVM) clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3"
I cannot help if you don't read the text.
"Known to work on these compilers" does not necessarily imply "known to *not* work on previous versions of these compilers". It could just mean it wasn't tested and thus is unknown whether it works or not.
On Mon, Apr 10, 2017 at 3:04 AM, Niall Douglas via Boost < boost@lists.boost.org> wrote: clang 3.5 (LLVM)
clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3
That's good, but as Edward pointed out knowing what values of -std= (or equivalent) are required is also needed. If the -std= default is acceptable, that should be mentioned too. Thanks, --Beman
clang 3.5 (LLVM) clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3
That's good, but as Edward pointed out knowing what values of -std= (or equivalent) are required is also needed. If the -std= default is acceptable, that should be mentioned too.
If a library clearly states at the top that it is a C++ 14 library, I'd think it obvious to start with -std=c++14 for older compilers needing that if you're manually configuring its usage. You've already documented it's a C++ 14 library. I don't think the documentation should suggest compiler flags as these vary between compilers and platforms and versions of the compiler and downstream use case. Besides, for anyone using cmake it is taken care for you anyway as cmake abstracts that nitty gritty away. BTW Outcome does compiler feature detection and complains loudly with useful error messages if you try using it on a compiler without sufficient C++ 14 features. Outcome also tells cmake what compiler features it needs. If it is accepted, it will tell Boost.Build the compiler features needed too. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On 4/10/2017 7:15 AM, Beman Dawes via Boost wrote:
On Mon, Apr 10, 2017 at 3:04 AM, Niall Douglas via Boost < boost@lists.boost.org> wrote:
clang 3.5 (LLVM)
clang 3.7 (with Microsoft Codegen) GCC 5.4 VS2015 Update 2 Xcode 7.3
That's good, but as Edward pointed out knowing what values of -std= (or equivalent) are required is also needed. If the -std= default is acceptable, that should be mentioned too.
The -std= default changes with each compiler/version so that is not necessary IMO for library authors to know or say. Niall mentioned C++14 so that is what is useful when someone says what their library needs. How C++14 translates to std= should be part of what the end-user should know when he uses a library with different compiler/versions. For instance my own particular setup for testing Boost libraries with Boost Build translates "c14" at the end of my own toolset "names" to the particular 'std=" switch for different compiler/versions I use for C++14 support. While this is usually "std=c++14" it does not have to be that, as sometimes something else works instead, such as "std=c++1y". Of course some compilers, aka VC++, can not be adjusted in such a way, so that it is also important for the end-user himself to know what level of compliance a particular compiler supports. I am far more concerned that library authors just state clearly what level of C++ compliance is needed to use their library and/or what level of C++ compliance is needed to use certain features of their library if those features differ from the general level. Of course stating what particular C++ construct support is needed, over and above basic C++1998/2003 support, also is helpful. As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects. I even note that a number of our current libraries do not do this, but should. It is much more understandable to get a preprocessor #error message specific to the C++ feature needed in such cases, than to get a nest of difficult to decipher compile failures for particular constructs.
On Apr 10, 2017, at 9:05 AM, Edward Diener via Boost <boost@lists.boost.org> wrote:
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects.
This should happen during configure step, so that the user gets an error before even building the library. Paul
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects.
This should happen during configure step, so that the user gets an error before even building the library.
A library's headers may have much lower demands on the C++ version than the source code. So your headers should still do feature checking and #error out. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On Mon, Apr 10, 2017 at 7:54 AM, Niall Douglas via Boost <boost@lists.boost.org> wrote:
So your headers should still do feature checking and #error out.
Beast is supposed to only require C++11. But I expect full support for C++11. So Visual Studio 2015 with anything less than Update 3 is not going to build correctly. I would love to check for specific updates, but I cannot find any Microsoft documentation on _MSC_VER or _MSC_FULL_VER that distinguishes between updates.
AMDG On 04/10/2017 08:35 AM, Paul Fultz II via Boost wrote:
On Apr 10, 2017, at 9:05 AM, Edward Diener via Boost <boost@lists.boost.org> wrote:
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects.
This should happen during configure step, so that the user gets an error before even building the library.
That works for libraries that have a configure step, which is not most Boost libraries. In Christ, Steven Watanabe
On 4/10/2017 10:35 AM, Paul Fultz II via Boost wrote:
On Apr 10, 2017, at 9:05 AM, Edward Diener via Boost <boost@lists.boost.org> wrote:
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects.
This should happen during configure step, so that the user gets an error before even building the library.
There is no "building the library" for header-only libraries in Boost. For non-header only libraries it is possible to use Boost Config's Build Time Configuration to determine whether or not the library can be built at all. I believe it should be possible to design a Boost Build jam file configuration facility, based on the check-target-builds rule, so that a Boost Build error is generated when the Boost Config C++ feature testing macros indicate the level of C++ compliance needed by a library is not met, but nobody has done that yet AFAIK.
course some compilers, aka VC++, can not be adjusted in such a way, so that it is also important for the end-user himself to know what level of compliance a particular compiler supports.
The newer MSVC's now have a /std: switch. You'll be glad to know it doesn't follow the same semantics as -std= because well, it's Microsoft. cmake 3.8 does not appear to understand the MSVC /std: switch yet because if you ask it for the C++ 17 standard when targeting MSVC, it pukes.
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects. I even note that a number of our current libraries do not do this, but should. It is much more understandable to get a preprocessor #error message specific to the C++ feature needed in such cases, than to get a nest of difficult to decipher compile failures for particular constructs.
Most of the compilers released during the last two years have varying support for C++17 feature test macros (VS2017 is very compliant here interestingly). If your library has no dependency on Boost, use those. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On 4/10/2017 10:53 AM, Niall Douglas via Boost wrote:
course some compilers, aka VC++, can not be adjusted in such a way, so that it is also important for the end-user himself to know what level of compliance a particular compiler supports.
The newer MSVC's now have a /std: switch. You'll be glad to know it doesn't follow the same semantics as -std= because well, it's Microsoft.
The new MSVC remains completely undocumented more than one month after it has been released, so whatever /std: switch it does have is guesswork AFAICS. But yes, if the new MSVC has such a switch it is an advance over the previous versions which just offered a single level of C++ compliance, whatever it was, which the end-user had to understand exactly.
cmake 3.8 does not appear to understand the MSVC /std: switch yet because if you ask it for the C++ 17 standard when targeting MSVC, it pukes.
As a side note I would really like to see libraries, which are tailored for Boost, use the Boost Config C++ feature testing macros to put out preprocessor #error messages when a feature that it needs is not supported during compilation, rather than letting the compiler simply fail because the construct in code cannot be parsed at the C++ conformance level the code expects. I even note that a number of our current libraries do not do this, but should. It is much more understandable to get a preprocessor #error message specific to the C++ feature needed in such cases, than to get a nest of difficult to decipher compile failures for particular constructs.
Most of the compilers released during the last two years have varying support for C++17 feature test macros (VS2017 is very compliant here interestingly). If your library has no dependency on Boost, use those.
Niall
On 11/04/2017 04:57, Edward Diener via Boost wrote:
On 4/10/2017 10:53 AM, Niall Douglas via Boost wrote:
The newer MSVC's now have a /std: switch. You'll be glad to know it doesn't follow the same semantics as -std= because well, it's Microsoft.
The new MSVC remains completely undocumented more than one month after it has been released, so whatever /std: switch it does have is guesswork AFAICS. But yes, if the new MSVC has such a switch it is an advance over the previous versions which just offered a single level of C++ compliance, whatever it was, which the end-user had to understand exactly.
There's an official blog post about it: https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche... And it's documented in the new doc wiki site (although the search is atrociously bad, so you can't find it unless you already know what you're looking for and even then have to navigate through several side paths before you can get to it): https://docs.microsoft.com/en-us/cpp/build/reference/std-specify-language-st...
On 04/11/17 02:24, Gavin Lambert via Boost wrote:
On 11/04/2017 04:57, Edward Diener via Boost wrote:
On 4/10/2017 10:53 AM, Niall Douglas via Boost wrote:
The newer MSVC's now have a /std: switch. You'll be glad to know it doesn't follow the same semantics as -std= because well, it's Microsoft.
The new MSVC remains completely undocumented more than one month after it has been released, so whatever /std: switch it does have is guesswork AFAICS. But yes, if the new MSVC has such a switch it is an advance over the previous versions which just offered a single level of C++ compliance, whatever it was, which the end-user had to understand exactly.
There's an official blog post about it:
https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche...
Blog is not documentation. One should not be required to follow blogs or other social media to know how to use a compiler.
On 11/04/2017 21:54, Andrey Semashev via Boost wrote:
On 04/11/17 02:24, Gavin Lambert via Boost wrote:
There's an official blog post about it:
https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche...
Blog is not documentation. One should not be required to follow blogs or other social media to know how to use a compiler.
Which is why the second link I posted was an official documentation link.
On 4/11/2017 6:58 PM, Gavin Lambert via Boost wrote:
On 11/04/2017 21:54, Andrey Semashev via Boost wrote:
On 04/11/17 02:24, Gavin Lambert via Boost wrote:
There's an official blog post about it:
https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche...
Blog is not documentation. One should not be required to follow blogs or other social media to know how to use a compiler.
Which is why the second link I posted was an official documentation link.
Finally they have their online docs and they just recently added downloadable local documentation. It "only" took them a month to have docs for their product. I am glad to be able to see the compiler switch docs for VC++17, which gives a good idea of the levels of C++ compliance which they support with VS2017. But again I do not see the issue of libraries having to document which compilers and in which modes they support rather than which level of coompliance the library supports. It is then up to the end-user to understand the compiler(s) being used and to use the proper compiler switches for a given library. My OP was to get library creators to take seriously the effort to specify the C++ compliance level(s) of their library in the library docs.
On Apr 12, 2017 1:13 AM, "Edward Diener via Boost" <boost@lists.boost.org> wrote: But again I do not see the issue of libraries having to document which compilers and in which modes they support rather than which level of coompliance the library supports. It is then up to the end-user to understand the compiler(s) being used and to use the proper compiler switches for a given library. My OP was to get library creators to take seriously the effort to specify the C++ compliance level(s) of their library in the library docs. I would just like to point out, that sometimes it's not enough to document *just* what's the minimum C++ standard a library requires, because we must not forget that compilers have plenty of bugs, irrespective of whether they support the required C++ features or not, so it is *also* necessary to document which specific version of compilers it's known to work with. Take Metal for instance, the only C++14 feature it requires are relaxed constant expressions, but there is a built in workaround for compilers that don't implement it, so it would technically be possible to use it even on a C++11 compiler that implements alias templates and in fact it works on MSVC 14 and GCC < 5 relying solely on C++11 features. However still MSVC 12 and the Intel Compiler are unable to pass a single unit test because they have serious issues with the kind of SFINAE Metal relies on. up until recently it also didn't work on GCC prior to 5, because of similar issues and it only works on MSVC 14 because of a myriad of workarounds and *a lot* of effort invested on working around it's many bugs. IOW in the case of Metal it's just as important to document which compilers it's known to work with as it is to state the level of C++ compliance required. Bruno
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Bruno Dutra via Boost Sent: 12 April 2017 06:55 To: Boost Developers List Cc: Bruno Dutra; Edward Diener Subject: Re: [boost] Libraries and C++ compliance
On Apr 12, 2017 1:13 AM, "Edward Diener via Boost" <boost@lists.boost.org> wrote:
But again I do not see the issue of libraries having to document which compilers and in which modes they support rather than which level of coompliance the library supports. It is then up to the end-user to understand the compiler(s) being used and to use the proper compiler switches for a given library. My OP was to get library creators to take seriously the effort to specify the C++ compliance level(s) of their library in the library docs.
I would just like to point out, that sometimes it's not enough to document *just* what's the minimum C++ standard a library requires, because we must not forget that compilers have plenty of bugs, irrespective of whether they support the required C++ features or not, so it is *also* necessary to document which specific version of compilers it's known to work with.
Take Metal for instance, the only C++14 feature it requires are relaxed constant expressions, but there is a built in workaround for compilers that don't implement it, so it would technically be possible to use it even on a C++11 compiler that implements alias templates and in fact it works on MSVC 14 and GCC < 5 relying solely on C++11 features. However still MSVC 12 and the Intel Compiler are unable to pass a single unit test because they have serious issues with the kind of SFINAE Metal relies on. up until recently it also didn't work on GCC prior to 5, because of similar issues and it only works on MSVC 14 because of a myriad of workarounds and *a lot* of effort invested on working around it's many bugs. IOW in the case of Metal it's just as important to document which compilers it's known to work with as it is to state the level of C++ compliance required.
+1 'Compliance with standard C++n ' is still a bit woolly - we haven't got any C++ compiler to a 'no known bugs' state. Failure to pass one library test doesn't necessarily mean that the library is not useful with that compiler - it may work usefully for many purposes. Passing all tests doesn't necessarily mean everything is perfect either. So I feel it is still helpful * to say which compilers passes all tests, so should work, * to say which compilers definitely won't work, * but also useful to say which compilers that probably or might work - but good luck ;-) Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 4/12/2017 1:55 AM, Bruno Dutra via Boost wrote:
On Apr 12, 2017 1:13 AM, "Edward Diener via Boost" <boost@lists.boost.org> wrote:
But again I do not see the issue of libraries having to document which compilers and in which modes they support rather than which level of coompliance the library supports. It is then up to the end-user to understand the compiler(s) being used and to use the proper compiler switches for a given library. My OP was to get library creators to take seriously the effort to specify the C++ compliance level(s) of their library in the library docs.
I would just like to point out, that sometimes it's not enough to document *just* what's the minimum C++ standard a library requires, because we must not forget that compilers have plenty of bugs, irrespective of whether they support the required C++ features or not, so it is *also* necessary to document which specific version of compilers it's known to work with.
I do not think it is necessary to document with which compilers a library works, but it may certainly be helpful, as in your case. But this is still usually secondary to documenting the level of C++ compliance needed, which is primary. Compilers can change, even though older versions of compilers tend not to be "fixed" once a later version of a compiler is issued. So documentation saying that library LLL works/does-not-work with compilerX/versionY/C++modeZ is valuable, but usually less so than being specific as possible about library LLL's level of C++ compliance and/or the C++ features it uses at any level of C++ compliance. My point is simply that if a library simply tells me only that it works with compilerX or with compilerX/versionY or even with compilerX/versionY/C++modeZ, it is not helpful to me at all if I need to know if it will work with compilerA/versionB/C++modeC. Whereas if it tells me the level of C++ compliance it needs and/or the C++ features it uses at any given level I usually have much better information about whether or not it will work with the compiler I am using.
Take Metal for instance, the only C++14 feature it requires are relaxed constant expressions, but there is a built in workaround for compilers that don't implement it, so it would technically be possible to use it even on a C++11 compiler that implements alias templates and in fact it works on MSVC 14 and GCC < 5 relying solely on C++11 features. However still MSVC 12 and the Intel Compiler are unable to pass a single unit test because they have serious issues with the kind of SFINAE Metal relies on.
These are great things to document. If a library has a fallback to using some lower level of C++ compliance that definitely needs to be documented. Again I wish to point out that even your remarks here, such as mentioning 'the Intel compiler', means very little to the end-user unless you mention versions and C++ compliance modes along with it in your official documentation.
up until recently it also didn't work on GCC prior to 5, because of similar issues and it only works on MSVC 14 because of a myriad of workarounds and *a lot* of effort invested on working around it's many bugs.
Well Boost PP "works" with the non-standard VC++ preprocessor of VC++ 8 through the latest version of VC++ just released ( call it 14.1 ) through many workarounds, but the doc does not have to say this explicitly IMO unless the end-user has to do something special to get it to work in some cases. Again I would be as specific as possible in the docs in Metal vis a vis certain compilers/versions/C++ compliance modes. I am not arguing in any way against such documentation.
IOW in the case of Metal it's just as important to document which compilers it's known to work with as it is to state the level of C++ compliance required.
Bruno
On Wed, Apr 12, 2017 at 2:01 PM, Edward Diener via Boost < boost@lists.boost.org> wrote:
On 4/12/2017 1:55 AM, Bruno Dutra via Boost wrote:
On Apr 12, 2017 1:13 AM, "Edward Diener via Boost" <boost@lists.boost.org
wrote:
But again I do not see the issue of libraries having to document which compilers and in which modes they support rather than which level of coompliance the library supports. It is then up to the end-user to understand the compiler(s) being used and to use the proper compiler switches for a given library. My OP was to get library creators to take seriously the effort to specify the C++ compliance level(s) of their library in the library docs.
I would just like to point out, that sometimes it's not enough to document *just* what's the minimum C++ standard a library requires, because we must not forget that compilers have plenty of bugs, irrespective of whether they support the required C++ features or not, so it is *also* necessary to document which specific version of compilers it's known to work with.
I do not think it is necessary to document with which compilers a library works, but it may certainly be helpful, as in your case. But this is still usually secondary to documenting the level of C++ compliance needed, which is primary. Compilers can change, even though older versions of compilers tend not to be "fixed" once a later version of a compiler is issued. So documentation saying that library LLL works/does-not-work with compilerX/versionY/C++modeZ is valuable, but usually less so than being specific as possible about library LLL's level of C++ compliance and/or the C++ features it uses at any level of C++ compliance.
My point is simply that if a library simply tells me only that it works with compilerX or with compilerX/versionY or even with compilerX/versionY/C++modeZ, it is not helpful to me at all if I need to know if it will work with compilerA/versionB/C++modeC. Whereas if it tells me the level of C++ compliance it needs and/or the C++ features it uses at any given level I usually have much better information about whether or not it will work with the compiler I am using.
I totally agree.
Take Metal for instance, the only C++14 feature it requires are relaxed
constant expressions, but there is a built in workaround for compilers that don't implement it, so it would technically be possible to use it even on a C++11 compiler that implements alias templates and in fact it works on MSVC 14 and GCC < 5 relying solely on C++11 features. However still MSVC 12 and the Intel Compiler are unable to pass a single unit test because they have serious issues with the kind of SFINAE Metal relies on.
These are great things to document. If a library has a fallback to using some lower level of C++ compliance that definitely needs to be documented. Again I wish to point out that even your remarks here, such as mentioning 'the Intel compiler', means very little to the end-user unless you mention versions and C++ compliance modes along with it in your official documentation.
I only realized this was not covered by the docs after reading this thread, I absolutely agree this is something worth of documenting, in fact I'm working on it.
up until recently
it also didn't work on GCC prior to 5, because of similar issues and it only works on MSVC 14 because of a myriad of workarounds and *a lot* of effort invested on working around it's many bugs.
Well Boost PP "works" with the non-standard VC++ preprocessor of VC++ 8 through the latest version of VC++ just released ( call it 14.1 ) through many workarounds, but the doc does not have to say this explicitly IMO unless the end-user has to do something special to get it to work in some cases.
Again I would be as specific as possible in the docs in Metal vis a vis certain compilers/versions/C++ compliance modes. I am not arguing in any way against such documentation.
I think novel libraries tend to emphasize the compilers on which they are tested, because they often rely on bleeding edge features that might only be available on fairly recent and specific compiler versions (think Boost.Hana), whereas mature libraries need not care about this as much, as compilers eventually catch up and features become mainstream. Bruno
On 4/10/2017 7:24 PM, Gavin Lambert via Boost wrote:
On 11/04/2017 04:57, Edward Diener via Boost wrote:
On 4/10/2017 10:53 AM, Niall Douglas via Boost wrote:
The newer MSVC's now have a /std: switch. You'll be glad to know it doesn't follow the same semantics as -std= because well, it's Microsoft.
The new MSVC remains completely undocumented more than one month after it has been released, so whatever /std: switch it does have is guesswork AFAICS. But yes, if the new MSVC has such a switch it is an advance over the previous versions which just offered a single level of C++ compliance, whatever it was, which the end-user had to understand exactly.
There's an official blog post about it:
https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche...
And it's documented in the new doc wiki site (although the search is atrociously bad, so you can't find it unless you already know what you're looking for and even then have to navigate through several side paths before you can get to it):
https://docs.microsoft.com/en-us/cpp/build/reference/std-specify-language-st...
It seems as if Microsoft has now decided to put their documentation online, but not currently viewable locally as help topics. Thanks for alerting me to this. Online docs are certainly better than no docs, even if the TOC, Index and Search are much worse, if not non-existent, online.
On 10 April 2017 at 10:57, Edward Diener via Boost <boost@lists.boost.org> wrote:
The new MSVC remains completely undocumented more than one month after it has been released ...
VS2017 == VS2015 Update 4 (as stated by MS) -> docs, see VS2015 Update 3.
... , so whatever /std: switch it does have is guesswork AFAICS. But yes, if the new MSVC has such a switch it is an advance over the previous versions which just offered a single level of C++ compliance, whatever it was, which the end-user had to understand exactly.
Not new, as you can see here https://blogs.msdn.microsoft.com/vcblog/2016/06/07/standards-version-switche... degski
On Sun, Apr 9, 2017 at 10:24 PM, Edward Diener via Boost < boost@lists.boost.org> wrote:
I would like to ask people who present new libraries to Boost, in whatever stages they are, to please specify in the documentation to the library and/or in messages regarding the library, what level of C++ compliance is needed to use the functionality of that library. This plea is not being directed at any particular current library being mentioned by anyone on the mailing list, but is a general plea regarding developers and their efforts.
I realize it is a real pain that C++ as a language, and as it continues to evolve, has a number of popular levels of C++ compliance. This is largely because C++ is offered by a number of different vendors in a number of different supported releases, each particular implementation supporting a number of levels of C++ compliance and sometimes only partially supporting a particular level of C++ compliance. But given this sometimes difficult situation I do not see it as enough for library docs/information to simply say "this library supports some-vendor/some-release" because this is actually fairly meaningless to me when I know that "some-vendor/some-release" supports a number of levels of C++ compliance through some compiler parameter ( often -std=something ). Therefore docs/information of "the library supports "some-implementation" or "the library is compliant with "more than one level of C++ compliance" tells me as much as if some one told me that the moon is yellow. So I am begging, pleading, entreating library authors to be specific about the C++ features or the C++ level of compliance needed to use their library, even if it is just a one-liner that succinctly explains what the end-user needs to know.
Furthermore, for any given library could we please have specific information about what will happen if I use the library, or some feature of the library, without the desired minimum level of C++ compliance. While I would assume compile-time compiler errors as the norm another possibility, especially given the excellent support in Boost Config to compiler conformance, are more readable preprocessor errors. Finally a library might offer some level of advanced C++ compliance but fall back to a lower level if possible.
Please, please library authors this is important. No end-user or tester of your library wants to spend extended time trying to figure out why some compile fails when the answer turns out simply to be one of inadequate C++ conformance level for a particular compiler implementation being used with a particular level of conformance.
+1 The requirements described above need to be added to the http://www.boost.org/development/requirements.html hierarchy, too. --Beman
FWIW - all libraries in the boost library incubator have a form filled out by the library author includes the same summary information. On of the fields in this form is C++ standard which indicates which standard version is required to use the library. I think every boost library should provide this information on this or a similar type form. Robert Ramey
participants (13)
-
Andrey Semashev -
Beman Dawes -
Bruno Dutra -
degski -
Edward Diener -
Gavin Lambert -
Niall Douglas -
Olaf van der Spek -
Paul A. Bristow -
Paul Fultz II -
Robert Ramey -
Steven Watanabe -
Vinnie Falco