[libcxx-commits] [PATCH] D103160: [libc++] Update ABI docs

[Arthur O'Dwyer via Phabricator via libcxx-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG287847dace44: [libc++] Update ABI docs. NFCI. (authored by arthur.j.odwyer).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D103160/new/

https://reviews.llvm.org/D103160

Files:
  libcxx/docs/DesignDocs/ABIVersioning.rst


Index: libcxx/docs/DesignDocs/ABIVersioning.rst
===================================================================
--- libcxx/docs/DesignDocs/ABIVersioning.rst
+++ libcxx/docs/DesignDocs/ABIVersioning.rst
@@ -3,15 +3,22 @@
 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``.
+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 ABI-breaking changes 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.
+To always use the most cutting-edge, most unstable ABI (which is currently ``2``
+but at some point will become ``3``), set the CMake option ``LIBCXX_ABI_UNSTABLE``.
+
+Internally, each ABI-changing feature is placed under its own C++ macro,
+``_LIBCPP_ABI_XXX``. These macros' definitions are controlled by the C++ macro
+``_LIBCPP_ABI_VERSION``, which is controlled by the ``LIBCXX_ABI_VERSION`` set
+at build time. Libc++ does not intend users to interact with these C++ macros
+directly.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D103160.355277.patch
Type: text/x-patch
Size: 2226 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20210629/67a5d023/attachment-0001.bin>