[libcxx-commits] [libcxx] 287847d - [libc++] Update ABI docs. NFCI.

[Arthur O'Dwyer via libcxx-commits]

Author: Arthur O'Dwyer
Date: 2021-06-29T12:39:23-04:00
New Revision: 287847dace4408a0e4e4bfbed7db4a4d1f3eba29

URL: https://github.com/llvm/llvm-project/commit/287847dace4408a0e4e4bfbed7db4a4d1f3eba29
DIFF: https://github.com/llvm/llvm-project/commit/287847dace4408a0e4e4bfbed7db4a4d1f3eba29.diff

LOG: [libc++] Update ABI docs. NFCI.

Differential Revision: https://reviews.llvm.org/D103160

Added: 
    

Modified: 
    libcxx/docs/DesignDocs/ABIVersioning.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/DesignDocs/ABIVersioning.rst b/libcxx/docs/DesignDocs/ABIVersioning.rst
index 5960dd18610c0..3b82f3cc60a44 100644
--- a/libcxx/docs/DesignDocs/ABIVersioning.rst
+++ b/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.