104 lines · plain
1========================2Symbol Visibility Macros3========================4 5.. contents::6 :local:7 8.. _visibility-macros:9 10Overview11========12 13Libc++ uses various "visibility" macros in order to provide a stable ABI in14both the library and the headers. These macros work by changing the15visibility and inlining characteristics of the symbols they are applied to.16 17The std namespace also has visibility attributes applied to avoid having to18add visibility macros in as many places. Namespace std has default19type_visibility to export RTTI and other type-specific information. Note that20type_visibility is only supported by Clang, so this doesn't replace21type-specific attributes. The only exception are enums, which GCC always gives22default visibility, thus removing the need for any annotations.23 24Visibility Macros25=================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 part32 of the libc++ library, type information and other symbols. On Windows,33 this macro applies `dllimport`/`dllexport` to the symbol, and on other34 platforms it gives the symbol default visibility. This macro should never be35 used on class templates. On classes it should only be used if the vtable36 lives in the built library.37 38**_LIBCPP_OVERRIDABLE_FUNC_VIS**39 Mark a symbol as being exported by the libc++ library, but allow it to be40 overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.41 This macro is applied to all `operator new` and `operator delete` overloads.42 43 **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden44 locally, since `dllimport` indicates the symbol should be bound to a separate45 DLL. All `operator new` and `operator delete` overloads are required to be46 locally overridable, and therefore must not be marked `dllimport`. On Windows,47 this macro therefore expands to `__declspec(dllexport)` when building the48 library and has an empty definition otherwise.49 50**_LIBCPP_HIDE_FROM_ABI**51 Mark a function as not being part of the ABI of any final linked image that52 uses it.53 54**_LIBCPP_HIDE_FROM_ABI_AFTER_V1**55 Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)56 when libc++ is built with an ABI version after ABI v1. This macro is used to57 maintain ABI compatibility for symbols that have been historically exported58 by libc++ in v1 of the ABI, but that we don't want to export in the future.59 60 This macro works as follows. When we build libc++, we either hide the symbol61 from the ABI (if the symbol is not part of the ABI in the version we're62 building), or we leave it included. From user code (i.e. when we're not63 building libc++), the macro always marks symbols as internal so that programs64 built using new libc++ headers stop relying on symbols that are removed from65 the ABI in a future version. Each time we release a new stable version of the66 ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can67 use it to start removing symbols from the ABI after that stable version.68 69**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**70 Mark the member functions, typeinfo, and vtable of the type named in71 an extern template declaration as being exported by the libc++ library.72 This attribute must be specified on all extern class template declarations.73 74 This macro is used to export the member functions produced by the explicit75 instantiation in the dylib.76 77 **Windows Behavior**: `extern template` and `dllexport` are fundamentally78 incompatible *on a class template* on Windows; the former suppresses79 instantiation, while the latter forces it. Specifying both on the same80 declaration makes the class template be instantiated, which is not desirable81 inside headers. This macro therefore expands to `dllimport` outside of libc++82 but nothing inside of it (rather than expanding to `dllexport`); instead, the83 explicit instantiations themselves are marked as exported. Note that this84 applies *only* to extern *class* templates. Extern *function* templates obey85 regular import/export semantics, and applying `dllexport` directly to the86 extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct87 thing to do for them.88 89**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**90 Mark the member functions, typeinfo, and vtable of an explicit instantiation91 of a class template as being exported by the libc++ library. This attribute92 must be specified on all class template explicit instantiations.93 94 It is only necessary to mark the explicit instantiation itself (as opposed to95 the extern template declaration) as exported on Windows, as discussed above.96 On all other platforms, this macro has an empty definition.97 98Links99=====100 101* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_102* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_103* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_104