[Bug libstdc++/99058] New: Consider adding a note about std::optional ABI break to the C++17 status table

[Bug libstdc++/99058] New: Consider adding a note about std::optional ABI break to the C++17 status table

[bspencer at blackberry dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

            Bug ID: 99058
           Summary: Consider adding a note about std::optional ABI break
                    to the C++17 status table
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: libstdc++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: bspencer at blackberry dot com
  Target Milestone: ---

In this table

https://gcc.gnu.org/onlinedocs/libstdc++/manual/status.html#status.iso.2017

the row labelled "Library Fundamentals V1 TS Components: optional" says it's
supported since "7.1" and references Note 1, but there's no mention of the ABI
break between 7.x and 8.x.

Perhaps I was misusing this table, but I interpreted "supported since 7.1" to
mean that if I compile against 7.1 headers, my code will remain ABI compatible
against future versions of the library _and_ other code compiled against future
versions of the headers.  This ABI break caught me by surprise, and even though
these versions are older now, it seems worthwhile to at least mention the break
in a note to help others.

BTW, this particular example also happens to come up as a question in Marshall
Clow's recent talk on the topic of standard library ABIs.  See
https://youtu.be/7RoTDjLLXJQ?t=3191

Thanks.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #1 from Jonathan Wakely <redi at gcc dot gnu.org> ---
C++17 support isn't stable until GCC 9 so there is no guarantee of
compatibility between 7 and 8 or 8 and 9. That applies to the entire library
(and language features) not just std::optional.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #2 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Brad Spencer from comment #0)
> Perhaps I was misusing this table, but I interpreted "supported since 7.1"
> to mean that if I compile against 7.1 headers, my code will remain ABI
> compatible against future versions of the library _and_ other code compiled
> against future versions of the headers.

Absolutely not.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[bspencer at blackberry dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #3 from Brad Spencer <bspencer at blackberry dot com> ---
(In reply to Jonathan Wakely from comment #1)
> C++17 support isn't stable until GCC 9 so there is no guarantee of
> compatibility between 7 and 8 or 8 and 9. That applies to the entire library
> (and language features) not just std::optional.

Ok.  What's the right way for me to learn what version of GCC has stable
support for a C++ version?  For example, where would I look to know that C++17
support isn't stable until GCC 9?  I can't seem to find that information on the
status page, but maybe I am looking in the wrong place.

(In reply to Jonathan Wakely from comment #2)
> (In reply to Brad Spencer from comment #0)
> > Perhaps I was misusing this table, but I interpreted "supported since 7.1"
> > to mean that if I compile against 7.1 headers, my code will remain ABI
> > compatible against future versions of the library _and_ other code compiled
> > against future versions of the headers.
> 
> Absolutely not.

Sorry.  I was imprecise in my wording.  I am not looking for or expecting any
guarantees.

I am under the (possibly mistaken) impression that the libstdc++ ABI (in a
given configuration) has been stable for a very long time, and that generally
integrators (such as Debian or Ubuntu, for example) provide versions of
libstdc++ that are ABI-compatible with code compiled against previous versions. 
As per https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html this is
reflected in the long-standing .so major version of 6.  I know there are many
caveats here, especially around the early introduction of pre-standardized
features, etc.

Is it correct to think that the _intention_ is that it is possible to configure
the library to remain ABI compatible into the future until a conscious decision
is made to introduce an ABI break?

Or, if I ever run code compiled with GCC N against the library from GCC N+1, am
I always at risk, with not even best efforts to lean on?

I'm not asking you to do more.  I just want to get a good understanding of the
circumstances of ABI stability.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #4 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Brad Spencer from comment #3)
> Ok.  What's the right way for me to learn what version of GCC has stable
> support for a C++ version?

The release notes:
https://gcc.gnu.org/gcc-9/changes.html#libstdcxx


> I am under the (possibly mistaken) impression that the libstdc++ ABI (in a
> given configuration) has been stable for a very long time, and that
> generally integrators (such as Debian or Ubuntu, for example) provide
> versions of libstdc++ that are ABI-compatible with code compiled against
> previous versions. 

The shared library ABI is stable. There are no std::optional symbols in the
shared library, so changes to std::optional do not affect the ABI of the shared
library (only of user code compiled using the libstdc++ headers).

> As per https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html this is
> reflected in the long-standing .so major version of 6.  I know there are
> many caveats here, especially around the early introduction of
> pre-standardized features, etc.

Right, like std::optional.

What matters is not whether the features has been standardized but whether it's
considered stable in GCC. The features don't suddenly become complete and
stable on the day that ISO publishes the next standard.

> Is it correct to think that the _intention_ is that it is possible to
> configure the library to remain ABI compatible into the future until a
> conscious decision is made to introduce an ABI break?

Only for parts of the library that are not considered experimental.

Support for C++17 in GCC 7 and 8 is experimental, as noted in the release
notes:
https://gcc.gnu.org/gcc-7/changes.html#libstdcxx
https://gcc.gnu.org/gcc-8/changes.html#libstdcxx

It is declared no longer experimental in GCC 9:
https://gcc.gnu.org/gcc-9/changes.html#libstdcxx

If you use experimental pieces (like C++17 support in GCC 8, or C++20 support
in GCC 10) then you are giving up the expectation of ABI stability between
releases.

https://stackoverflow.com/questions/46746878/is-it-safe-to-link-c17-c14-and-c11-objects/49119902#49119902

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #5 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Jonathan Wakely from comment #1)
> C++17 support isn't stable until GCC 9 so there is no guarantee of
> compatibility between 7 and 8 or 8 and 9. That applies to the entire library
> (and language features) not just std::optional.

I should clarify that what "applies to the entire library" is the experimental
nature of C++17 features. But C++98/11/14 features like std::vector and
std::shared_ptr are compatible between GCC 7 and later releases.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #6 from Jonathan Wakely <redi at gcc dot gnu.org> ---
I think the following doc patch would probably help.


--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -24,6 +24,8 @@ features. See <link
linkend="manual.intro.using.flags">dialect</link>
 options. The pre-defined symbol
 <constant>__cplusplus</constant> is used to check for the
 presence of the required flag.
+GCC 5.1 was the first release with non-experimental C++11 support,
+so the API and ABI of C++11 components is only stable from that release on.
 </para>

 <para>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
index 61bea5adad5..af4bb6dc736 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
@@ -17,6 +17,8 @@ features. See <link
linkend="manual.intro.using.flags">dialect</link>
 options. The pre-defined symbol
 <constant>__cplusplus</constant> is used to check for the
 presence of the required flag.
+GCC 6.1 was the first release with non-experimental C++14 support,
+so the API and ABI of C++14 components is only stable from that release on.
 </para>

 <para>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
index aa34b8c3cf5..a3c23ba54e8 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
@@ -17,6 +17,8 @@ features. See <link
linkend="manual.intro.using.flags">dialect</link>
 options. The pre-defined symbol
 <constant>__cplusplus</constant> is used to check for the
 presence of the required flag.
+GCC 9.1 was the first release with non-experimental C++17 support,
+so the API and ABI of C++17 components is only stable from that release on.
 </para>

 <para>

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #7 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Jonathan Wakely from comment #6)
> +GCC 5.1 was the first release with non-experimental C++11 support,
> +so the API and ABI of C++11 components is only stable from that release on.

Maybe this should say "of new C++11 components" (and similarly in the other
sections) to make it clear that it only applies to features added by C++11, and
not everything in the C++11 status table.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[bspencer at blackberry dot com]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #8 from Brad Spencer <bspencer at blackberry dot com> ---
Everything you've said makes sense to me.  The proposed documentation changes
would help a lot.  IMO, they are a good idea and would have helped (and will
continue to help) me.

I agree that the C++11/14/17 status page for libstdc++ and the compiler itself)
are great places to document the version of GCC at which those features became
stable.

BTW, the compiler's own C++ status page seems to make some statements that,
while perhaps not technically contradictory, might be misleading, or at least
confusing when taken together with your new doc changes.

For example:

https://gcc.gnu.org/projects/cxx-status.html#cxx11

"GCC 4.8.1 was the first feature-complete implementation of the 2011 C++
standard"

That's probably true, but the information that you wrote in the new diff is
more important to a typical GCC user.  Perhaps this should also state when
C++11 became stable?

The compiler's C++14 section doesn't list a version, and its C++17 section says
"C++17 features are available since GCC 5".

(In reply to Jonathan Wakely from comment #7)
> > +GCC 5.1 was the first release with non-experimental C++11 support,
> > +so the API and ABI of C++11 components is only stable from that release on.
> 
> Maybe this should say "of new C++11 components" (and similarly in the other
> sections) to make it clear that it only applies to features added by C++11,
> and not everything in the C++11 status table.

Perhaps "so the API and ABI of components added in C++11"?

Thanks again for explaining this in detail and for the changes.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #9 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Jonathan Wakely <redi@gcc.gnu.org>:

https://gcc.gnu.org/g:ce43c906049b828c0472d8499b52ac6233c869d0

commit r11-7194-gce43c906049b828c0472d8499b52ac6233c869d0
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Feb 11 15:35:23 2021 +0000

    libstdc++: Document when C++11/14/17 support became stable [PR 99058]

    libstdc++-v3/ChangeLog:

            PR libstdc++/99058
            * doc/xml/manual/status_cxx2011.xml: Document when support
            became stable.
            * doc/xml/manual/status_cxx2014.xml: Likewise.
            * doc/xml/manual/status_cxx2017.xml: Likewise.
            * doc/html/manual/status.html: Regenerate.

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
   Last reconfirmed|                            |2021-02-12
           Assignee|unassigned at gcc dot gnu.org      |redi at gcc dot gnu.org
     Ever confirmed|0                           |1
             Status|UNCONFIRMED                 |ASSIGNED
   Target Milestone|---                         |8.5

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #10 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The releases/gcc-10 branch has been updated by Jonathan Wakely
<redi@gcc.gnu.org>:

https://gcc.gnu.org/g:8c4620e0b085911293bd501232cdc31c81b67512

commit r10-9584-g8c4620e0b085911293bd501232cdc31c81b67512
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Feb 11 15:35:23 2021 +0000

    libstdc++: Document when C++11/14/17 support became stable [PR 99058]

    libstdc++-v3/ChangeLog:

            PR libstdc++/99058
            * doc/xml/manual/status_cxx2011.xml: Document when support
            became stable.
            * doc/xml/manual/status_cxx2014.xml: Likewise.
            * doc/xml/manual/status_cxx2017.xml: Likewise.
            * doc/html/manual/status.html: Regenerate.

    (cherry picked from commit ce43c906049b828c0472d8499b52ac6233c869d0)

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #11 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The releases/gcc-9 branch has been updated by Jonathan Wakely
<redi@gcc.gnu.org>:

https://gcc.gnu.org/g:2ede3f69d27e082cbba69b77e9807b06e3ad1730

commit r9-9357-g2ede3f69d27e082cbba69b77e9807b06e3ad1730
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Feb 11 15:35:23 2021 +0000

    libstdc++: Document when C++11/14/17 support became stable [PR 99058]

    libstdc++-v3/ChangeLog:

            PR libstdc++/99058
            * doc/xml/manual/status_cxx2011.xml: Document when support
            became stable.
            * doc/xml/manual/status_cxx2014.xml: Likewise.
            * doc/xml/manual/status_cxx2017.xml: Likewise.
            * doc/html/manual/status.html: Regenerate.

    (cherry picked from commit ce43c906049b828c0472d8499b52ac6233c869d0)

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

--- Comment #12 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The releases/gcc-8 branch has been updated by Jonathan Wakely
<redi@gcc.gnu.org>:

https://gcc.gnu.org/g:07b4b069b34262b77e4295e57351bad49f3c4d06

commit r8-10848-g07b4b069b34262b77e4295e57351bad49f3c4d06
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Feb 11 15:35:23 2021 +0000

    libstdc++: Document when C++11/14/17 support became stable [PR 99058]

    libstdc++-v3/ChangeLog:

            PR libstdc++/99058
            * doc/xml/manual/status_cxx2011.xml: Document when support
            became stable.
            * doc/xml/manual/status_cxx2014.xml: Likewise.
            * doc/xml/manual/status_cxx2017.xml: Likewise.
            * doc/html/manual/status.html: Regenerate.

    (cherry picked from commit ce43c906049b828c0472d8499b52ac6233c869d0)

[Bug libstdc++/99058] Consider adding a note about std::optional ABI break to the C++17 status table

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99058

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |FIXED
             Status|ASSIGNED                    |RESOLVED

--- Comment #13 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Done in all active branches.