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

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

Quuxplusone created this revision.
Quuxplusone added reviewers: ldionne, libc++, Mordante.
Quuxplusone added a project: libc++.
Quuxplusone requested review of this revision.
Herald added a subscriber: libcxx-commits.
Herald added 1 blocking reviewer(s): libc++.

Repository:
  rG LLVM Github Monorepo

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,21 @@
 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``.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D103160.347935.patch
Type: text/x-patch
Size: 2159 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20210526/91180f5f/attachment-0001.bin>