[libc++] Fix and document visibility attributes for Clang, GCC and Windows.
Summary:
This patch fixes a number of problems with the visibility macros across GCC (on Unix) and Windows (DLL import/export semantics). All of the visibility macros are now documented under `DesignDocs/VisibilityMacros.rst`. Now I'll no longer forget the subtleties of each!
This patch adds two new visibility macros:
* `_LIBCPP_ENUM_VIS` for controlling the typeinfo of enum types. Only Clang supports this.
* `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` for redefining visibility on explicit instantiation declarations. Clang and Windows require this.
After applying this patch GCC only emits one -Wattribute warning opposed to 30+.
Reviewers: mclow.lists, EricWF
Subscribers: beanz, mgorny, cfe-commits
Differential Revision: https://reviews.llvm.org/D24602
llvm-svn: 281673
Cr-Mirrored-From: sso://chromium.googlesource.com/_direct/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: 49e2967f2709b6333ae9373cf304af97a3ea785f
diff --git a/docs/DesignDocs/VisibilityMacros.rst b/docs/DesignDocs/VisibilityMacros.rst
new file mode 100644
index 0000000..6e2294d
--- /dev/null
+++ b/docs/DesignDocs/VisibilityMacros.rst
@@ -0,0 +1,85 @@
+========================
+Symbol Visibility Macros
+========================
+
+.. contents::
+ :local:
+
+Overview
+========
+
+Libc++ uses various "visibility" macros in order to provide a stable ABI in
+both the library and the headers. These macros work by changing the
+visibility and inlining characteristics of the symbols they are applied to.
+
+Visibility Macros
+=================
+
+**_LIBCPP_HIDDEN**
+ Mark a symbol as hidden so it will not be exported from shared libraries.
+
+**_LIBCPP_FUNC_VIS**
+ Mark a symbol as being exported by the libc++ library. This attribute must
+ be applied to the declaration of all functions exported by the libc++ dylib.
+
+**_LIBCPP_INLINE_VISIBILITY**
+ Mark a function as hidden and force inlining whenever possible.
+
+**_LIBCPP_ALWAYS_INLINE**
+ A synonym for `_LIBCPP_INLINE_VISIBILITY`
+
+**_LIBCPP_TYPE_VIS**
+ Mark a type's typeinfo and vtable as having default visibility.
+ `_LIBCPP_TYPE_VIS`. This macro has no effect on the visibility of the
+ type's member functions. This attribute cannot be used on class templates.
+
+ **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
+ attribute. With GCC the `visibility(...)` attribute is used and member
+ functions are affected.
+
+**_LIBCPP_TYPE_VIS_ONLY**
+ The same as `_LIBCPP_TYPE_VIS` except that it may be applied to templates.
+
+ **Windows Behavior**: DLLs do not support dllimport/export on class templates.
+ The macro has an empty definition on this platform.
+
+ Note: This macro should be renamed `_LIBCPP_TEMPLATE_TYPE_VIS`.
+
+**_LIBCPP_ENUM_VIS**
+ Mark the typeinfo of an enum as having default visibility. This attribute
+ should be applied to all enum declarations.
+
+ **Windows Behavior**: DLLs do not support importing or exporting enumeration
+ typeinfo. The macro has an empty definition on this platform.
+
+ **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
+ if `-fvisibility=hidden` is specified. Additionally applying a visibility
+ attribute to an enum class results in a warning. The macro has an empty
+ definition with GCC.
+
+**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
+ Mark the member functions, typeinfo, and vtable of the type named in
+ a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
+ This attribute must be specified on all extern class template declarations.
+
+ This macro is used to override the `_LIBCPP_TYPE_VIS_ONLY` attribute
+ specified on the primary template and to export the member functions produced
+ by the explicit instantiation in the dylib.
+
+ **GCC Behavior**: GCC ignores visibility attributes applied the type in
+ extern template declarations and applying an attribute results in a warning.
+ However since `_LIBCPP_TYPE_VIS_ONLY` is the same as `_LIBCPP_TYPE_VIS` the
+ visibility is already correct. The macro has an empty definition with GCC.
+
+**_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*.
+ Exception types must be defined directly in namespace `std` and not the
+ versioning namespace.
+
+Links
+=====
+
+* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
+* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
+* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_