[libc++] Add the _LIBCPP_HIDE_FROM_ABI_AFTER_V1 macro

Summary:
This macro allows hiding symbols from the ABI when the library is built
with an ABI version after ABI v1, which is currently the only stable ABI.
This commit defines `_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY` to be
`_LIBCPP_HIDE_FROM_ABI_AFTER_V1`, meaning that symbols that were only
exported by the library for historical reasons are not exported anymore
in the unstable ABI.

Because of that, this commit is an ABI break for ABI v2. This ABI version
is not stable, however, so this should not be a problem.

Reviewers: EricWF, mclow.lists

Subscribers: christof, dexonsmith, cfe-commits

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

llvm-svn: 339012

1 files changed, 15 insertions, 9 deletions

diff --git a/libcxx/docs/DesignDocs/VisibilityMacros.rst b/libcxx/docs/DesignDocs/VisibilityMacros.rst
index 878566ea0bc..493b445750e 100644
--- a/libcxx/docs/DesignDocs/VisibilityMacros.rst
+++ b/libcxx/docs/DesignDocs/VisibilityMacros.rst
@@ -46,6 +46,21 @@ Visibility Macros
   other words, the address of a function marked with this attribute is not
   guaranteed to be the same across translation units.
 
+**_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
+  Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
+  when libc++ is built with an ABI version after ABI v1. This macro is used to
+  maintain ABI compatibility for symbols that have been historically exported
+  by libc++ in v1 of the ABI, but that we don't want to export in the future.
+
+  This macro works as follows. When we build libc++, we either hide the symbol
+  from the ABI (if the symbol is not part of the ABI in the version we're
+  building), or we leave it included. From user code (i.e. when we're not
+  building libc++), the macro always marks symbols as internal so that programs
+  built using new libc++ headers stop relying on symbols that are removed from
+  the ABI in a future version. Each time we release a new stable version of the
+  ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
+  use it to start removing symbols from the ABI after that stable version.
+
 **_LIBCPP_TYPE_VIS**
   Mark a type's typeinfo, vtable and members as having default visibility.
   This attribute cannot be used on class templates.
@@ -139,15 +154,6 @@ Visibility Macros
   against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
   `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
 
-**_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY**
-  Mark a member function of a class template as visible and always inline. This
-  macro should only be applied to member functions of class templates that are
-  externally instantiated. It is important that these symbols are not marked
-  as hidden as that will prevent the dylib definition from being found.
-
-  This macro is used to maintain ABI compatibility for symbols that have been
-  historically exported by the libc++ library but are now marked inline.
-
 **_LIBCPP_EXCEPTION_ABI**
   Mark the member functions, typeinfo, and vtable of the type as being exported
   by the libc++ library. This macro must be applied to all *exception types*.