libcxx/docs/DesignDocs/VisibilityMacros.rst

   1 ========================
   2 Symbol Visibility Macros
   3 ========================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _visibility-macros:
   9
  10 Overview
  11 ========
  12
  13 Libc++ uses various "visibility" macros in order to provide a stable ABI in
  14 both the library and the headers. These macros work by changing the
  15 visibility and inlining characteristics of the symbols they are applied to.
  16
  17 The std namespace also has visibility attributes applied to avoid having to
  18 add visibility macros in as many places. Namespace std has default
  19 type_visibility to export RTTI and other type-specific information. Note that
  20 type_visibility is only supported by Clang, so this doesn't replace
  21 type-specific attributes. The only exception are enums, which GCC always gives
  22 default visibility, thus removing the need for any annotations.
  23
  24 Visibility Macros
  25 =================
  26
  27 **_LIBCPP_HIDDEN**
  28   Mark a symbol as hidden so it will not be exported from shared libraries.
  29
  30 **_LIBCPP_EXPORTED_FROM_ABI**
  31   Mark a symbol as being part of our ABI. This includes functions that are part
  32   of the libc++ library, type information and other symbols. On Windows,
  33   this macro applies `dllimport`/`dllexport` to the symbol, and on other
  34   platforms it gives the symbol default visibility.
  35
  36 **_LIBCPP_OVERRIDABLE_FUNC_VIS**
  37   Mark a symbol as being exported by the libc++ library, but allow it to be
  38   overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
  39   This macro is applied to all `operator new` and `operator delete` overloads.
  40
  41   **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
  42   locally, since `dllimport` indicates the symbol should be bound to a separate
  43   DLL. All `operator new` and `operator delete` overloads are required to be
  44   locally overridable, and therefore must not be marked `dllimport`. On Windows,
  45   this macro therefore expands to `__declspec(dllexport)` when building the
  46   library and has an empty definition otherwise.
  47
  48 **_LIBCPP_HIDE_FROM_ABI**
  49   Mark a function as not being part of the ABI of any final linked image that
  50   uses it.
  51
  52 **_LIBCPP_INLINE_VISIBILITY**
  53   Historical predecessor of ``_LIBCPP_HIDE_FROM_ABI`` -- please use
  54   ``_LIBCPP_HIDE_FROM_ABI`` instead.
  55
  56 **_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
  57   Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
  58   when libc++ is built with an ABI version after ABI v1. This macro is used to
  59   maintain ABI compatibility for symbols that have been historically exported
  60   by libc++ in v1 of the ABI, but that we don't want to export in the future.
  61
  62   This macro works as follows. When we build libc++, we either hide the symbol
  63   from the ABI (if the symbol is not part of the ABI in the version we're
  64   building), or we leave it included. From user code (i.e. when we're not
  65   building libc++), the macro always marks symbols as internal so that programs
  66   built using new libc++ headers stop relying on symbols that are removed from
  67   the ABI in a future version. Each time we release a new stable version of the
  68   ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
  69   use it to start removing symbols from the ABI after that stable version.
  70
  71 **_LIBCPP_TEMPLATE_VIS**
  72   Mark a type's typeinfo and vtable as having default visibility.
  73   This macro has no effect on the visibility of the type's member functions.
  74
  75   **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
  76   attribute. With GCC the `visibility(...)` attribute is used and member
  77   functions are affected.
  78
  79   **Windows Behavior**: DLLs do not support dllimport/export on class templates.
  80   The macro has an empty definition on this platform.
  81
  82 **_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
  83   Mark the member functions, typeinfo, and vtable of the type named in
  84   an extern template declaration as being exported by the libc++ library.
  85   This attribute must be specified on all extern class template declarations.
  86
  87   This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute
  88   specified on the primary template and to export the member functions produced
  89   by the explicit instantiation in the dylib.
  90
  91   **Windows Behavior**: `extern template` and `dllexport` are fundamentally
  92   incompatible *on a class template* on Windows; the former suppresses
  93   instantiation, while the latter forces it. Specifying both on the same
  94   declaration makes the class template be instantiated, which is not desirable
  95   inside headers. This macro therefore expands to `dllimport` outside of libc++
  96   but nothing inside of it (rather than expanding to `dllexport`); instead, the
  97   explicit instantiations themselves are marked as exported. Note that this
  98   applies *only* to extern *class* templates. Extern *function* templates obey
  99   regular import/export semantics, and applying `dllexport` directly to the
 100   extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
 101   thing to do for them.
 102
 103 **_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
 104   Mark the member functions, typeinfo, and vtable of an explicit instantiation
 105   of a class template as being exported by the libc++ library. This attribute
 106   must be specified on all class template explicit instantiations.
 107
 108   It is only necessary to mark the explicit instantiation itself (as opposed to
 109   the extern template declaration) as exported on Windows, as discussed above.
 110   On all other platforms, this macro has an empty definition.
 111
 112 **_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS**
 113   Mark a symbol as hidden so it will not be exported from shared libraries. This
 114   is intended specifically for method templates of either classes marked with
 115   `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation
 116   declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`.
 117
 118   When building libc++ with hidden visibility, we want explicit template
 119   instantiations to export members, which is consistent with existing Windows
 120   behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export
 121   their members, which is again consistent with existing Windows behavior.
 122   Both these changes are necessary for clients to be able to link against a
 123   libc++ DSO built with hidden visibility without encountering missing symbols.
 124
 125   An unfortunate side effect, however, is that method templates of classes
 126   either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation
 127   declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default
 128   visibility when instantiated. These methods are often implicitly instantiated
 129   inside other libraries which use the libc++ headers, and will therefore end up
 130   being exported from those libraries, since those implicit instantiations will
 131   receive default visibility. This is not acceptable for libraries that wish to
 132   control their visibility, and led to PR30642.
 133
 134   Consequently, all such problematic method templates are explicitly marked
 135   either hidden (via this macro) or inline, so that they don't leak into client
 136   libraries. The problematic methods were found by running
 137   `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_
 138   against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
 139   `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
 140
 141 Links
 142 =====
 143
 144 * `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
 145 * `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
 146 * `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_