[libc++] Update ABI docs

[Mordante]

I like this, the text looks much better now. Did you verify whether the documentation changes build locally? If not can you rebase the patch after Buildkite becomes stable again?

libcxx/docs/DesignDocs/ABIVersioning.rst

15

I dislike unstable here.

[• Quuxplusone]

Change "new unstable features" to "new ABI-breaking features" per @Mordante

[ldionne]

We need to decide whether the ABI version is something that can be selected by users when they use libc++, or whether it's something that's baked in when the library is built and shipped (usually by a vendor). In my opinion, the former doesn't make sense, because the ABI version has an influence on what is provided in the .so - so the behavior of the headers has to match exactly how the .so was built. I'd like to get a common understanding and agreement that this is how things should work.

If we're all on the same page with that, I would not mention the _LIBCPP_ABI_VERSION macro anywhere since it can be considered an implementation detail of the library. The only thing that really matters is the LIBCXX_ABI_VERSION CMake setting, which is set when libc++ is built/packaged. I would also drop the mention of _LIBCPP_ABI_UNSTABLE.

[mclow.lists]

In D103160#2784959, @ldionne wrote:

We need to decide whether the ABI version is something that can be selected by users when they use libc++, or whether it's something that's baked in when the library is built and shipped (usually by a vendor). In my opinion, the former doesn't make sense, because the ABI version has an influence on what is provided in the .so - so the behavior of the headers has to match exactly how the .so was built. I'd like to get a common understanding and agreement that this is how things should work.

I concur. It's "baked in" when libc++ is built.

[• Quuxplusone]

libcxx/docs/DesignDocs/ABIVersioning.rst

23

@ldionne wrote:

If we're all on the same page with that, I would not mention the _LIBCPP_ABI_VERSION macro anywhere since it can be considered an implementation detail of the library. The only thing that really matters is the LIBCXX_ABI_VERSION CMake setting, which is set when libc++ is built/packaged. I would also drop the mention of _LIBCPP_ABI_UNSTABLE.

I'm willing to stipulate that end-users should mess only with LIBCXX_ABI_VERSION (and never touch any of the individual _LIBCPP_ABI_XXX macros directly); however, I still think it's worth mentioning these macros somehow in this design doc, because otherwise we have literally no documentation of the C++ macro design, and I assume collecting that kind of documentation is the entire point of this "DesignDocs" directory.

How about I talk about the CMake flags first, and then start a new paragraph with "Internally, each ABI-changing feature is placed under... ...Libc++ does not intend users to interact with these C++ macros directly."

[• Quuxplusone]

Updated in the general direction of @ldionne's and @mclow.lists's review comments. What do we think of this now?

[Mordante]

LGTM, but please wait for the reaction of @ldionne and @mclow.lists.

[SeanP]

libcxx/docs/DesignDocs/ABIVersioning.rst

15

What is the intension when version "2" becomes stable? Vendors will have compilers in service that support version 1 and the vendor customers will have many applications and shared libraries that use version 1. What will happen when the vendor wants to step up to version 2? Will the vendor be able to ship both version 1 & version 2? Will applications be able to use both versions either via object file dependencies (eg. static libs) or via shared libraries? Or is there a complete breakage? I hope that is not the case as that would force 3rd party providers to provide two versions of any shared library they sell.

[• Quuxplusone]

@ldionne and @mclow.lists , how does this look now? I still claim it's a step in the forward direction, and would like to get it landed.

libcxx/docs/DesignDocs/ABIVersioning.rst

15

I don't know, but I bet "there is a complete breakage" is closest to the truth.
One thing that's not mentioned in this doc (that probably should be): libc++ nests everything under a C++11 "inline namespace," e.g. std::any is really named std::__1::any. The __1 corresponds to C++ macro _LIBCPP_ABI_NAMESPACE, which is constructed out of the _LIBCPP_ABI_VERSION. So, if you step up to version 2, you'll find that all your standard library stuff has moved to e.g. std::__2::any.
You almost certainly won't be able to ship a shared library that works equally well with either std::__1 or std::__2. That's kind of the definition of an ABI break.
Vice versa, while _LIBCPP_ABI_NAMESPACE affects the mangling of std::any, it doesn't affect the mangling of struct Your::M : std::any {}, which has all the same problems as std::any, ABI-wise. https://godbolt.org/z/qj7fWzbrx

[ldionne]

I think this looks really good now, thanks a lot and sorry for the delay!

libcxx/docs/DesignDocs/ABIVersioning.rst

15

What is the intension when version "2" becomes stable?

I don't foresee a point where we will say version 1 doesn't exist anymore. That would imply forcing an ABI break on all vendors simultaneously, which is both a crazy idea and not up to an open source community to decide, IMO.

What I could see happening is that we'll provide version 1, but also provide a stable version 2 that vendors can individually opt into, if it's possible for them to do so. For example, most vendors have an occasion to perform a complete ABI break when they introduce a new architecture, since no software exists on that architecture at the start. That's an open door for them to pick the newer yet stable ABI v2 (once it is stable).

If we do come to a point (a long time from now) where we are OK with dropping support for v1 completely (e.g. because nobody ships it anymore), then we could remove it.

libcxx/docs/DesignDocs/ABIVersioning.rst

 
 ====================
 Libc++ ABI stability
 ====================
 
-Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI
-is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking
-improvements and bugfixes for the scenarios when ABI change is not a issue.
+Libc++ aims to preserve a stable ABI to avoid subtle bugs when code built under the old ABI
+is linked with code built under the new ABI. At the same time, libc++ wants to make
+ABI-breaking improvements and bugfixes in scenarios where the user doesn't mind ABI breaks.
 
-To support both cases, libc++ allows specifying the ABI version at the
-build time.  The version is defined with a cmake option
-LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to
-include all present ABI breaking features. These options translate
-into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE.
+To support both cases, libc++ allows specifying an ABI version at
+build time. The version is defined with CMake option
+``LIBCXX_ABI_VERSION``, which corresponds to the C++ macro ``_LIBCPP_ABI_VERSION``.
+Currently supported values are ``1`` (the stable default)
+and ``2`` (the unstable "next" version). At some point "ABI version 2" will be
+frozen and new unstable features will start being applied to version ``3``;
+but this has not happened yet.
 
-Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled
-based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once.
+Each ABI-changing feature is placed under its own C++ macro, ``_LIBCPP_ABI_XXX``,
+which is enabled based on the value of ``_LIBCPP_ABI_VERSION``.
+
+To always use the most cutting-edge, most unstable ABI, which enables all
+``_LIBCPP_ABI_XXX`` improvements, use the CMake option ``LIBCXX_ABI_UNSTABLE``,
+which corresponds to the C++ macro ``_LIBCPP_ABI_UNSTABLE``.