1======================== 2Symbol Visibility Macros 3======================== 4 5.. contents:: 6 :local: 7 8.. _visibility-macros: 9 10Overview 11======== 12 13Libc++ uses various "visibility" macros in order to provide a stable ABI in 14both the library and the headers. These macros work by changing the 15visibility and inlining characteristics of the symbols they are applied to. 16 17The std namespace also has visibility attributes applied to avoid having to 18add visibility macros in as many places. Namespace std has default 19type_visibility to export RTTI and other type-specific information. Note that 20type_visibility is only supported by Clang, so this doesn't replace 21type-specific attributes. The only exception are enums, which GCC always gives 22default visibility, thus removing the need for any annotations. 23 24Visibility 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 141Links 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>`_ 147