ABI versioning macros for libc++.

C++ macros and CMake options that specify the default ABI version of
the library, and can be overridden to pick up new ABI-changing
features.

llvm-svn: 250254

2 files changed, 36 insertions, 0 deletions

diff --git a/libcxx/docs/Abi.rst b/libcxx/docs/Abi.rst
new file mode 100644
index 00000000000..5960dd18610
--- /dev/null
+++ b/libcxx/docs/Abi.rst
@@ -0,0 +1,17 @@
+
+====================
+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.
+
+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.
+
+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.
diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst
index e343dfddbf9..6e45578dbb9 100644
--- a/libcxx/docs/BuildingLibcxx.rst
+++ b/libcxx/docs/BuildingLibcxx.rst
@@ -193,6 +193,25 @@ libc++ Feature options
 
   Build libc++ with run time type information.
 
+
+libc++ Feature options
+----------------------
+
+The following options allow building libc++ for a different ABI version.
+
+.. option:: LIBCXX_ABI_VERSION:STRING
+
+  **Default**: ``1``
+
+  Defines the target ABI version of libc++.
+
+.. option:: LIBCXX_ABI_UNSTABLE:BOOL
+
+  **Default**: ``OFF``
+
+  Build the "unstable" ABI version of libc++. Includes all ABI changing features
+  on top of the current stable version.
+
 .. _LLVM-specific variables:
 
 LLVM-specific options