shylie/llvm-project
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

[libc++] Update ABI docs. NFCI.

Browse Source 
Differential Revision: https://reviews.llvm.org/D103160
This commit is contained in:
Arthur O'Dwyer 2021-05-26 08:59:16 -04:00
parent 9ccdaac8f9
commit 287847dace
1 changed files with 17 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
libcxx/docs/DesignDocs/ABIVersioning.rst
View File

@ -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.