1======================== 2Symbol Visibility Macros 3======================== 4 5.. contents:: 6 :local: 7 8Overview 9======== 10 11Libc++ uses various "visibility" macros in order to provide a stable ABI in 12both the library and the headers. These macros work by changing the 13visibility and inlining characteristics of the symbols they are applied to. 14 15Visibility Macros 16================= 17 18**_LIBCPP_HIDDEN** 19 Mark a symbol as hidden so it will not be exported from shared libraries. 20 21**_LIBCPP_FUNC_VIS** 22 Mark a symbol as being exported by the libc++ library. This attribute must 23 be applied to the declaration of all functions exported by the libc++ dylib. 24 25**_LIBCPP_EXPORTED_FROM_ABI** 26 Mark a symbol as being exported by the libc++ library. This attribute may 27 only be applied to objects defined in the libc++ runtime library. On Windows, 28 this macro applies `dllimport`/`dllexport` to the symbol, and on other 29 platforms it gives the symbol default visibility. 30 31**_LIBCPP_OVERRIDABLE_FUNC_VIS** 32 Mark a symbol as being exported by the libc++ library, but allow it to be 33 overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`. 34 This macro is applied to all `operator new` and `operator delete` overloads. 35 36 **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden 37 locally, since `dllimport` indicates the symbol should be bound to a separate 38 DLL. All `operator new` and `operator delete` overloads are required to be 39 locally overridable, and therefore must not be marked `dllimport`. On Windows, 40 this macro therefore expands to `__declspec(dllexport)` when building the 41 library and has an empty definition otherwise. 42 43**_LIBCPP_HIDE_FROM_ABI** 44 Mark a function as not being part of the ABI of any final linked image that 45 uses it. 46 47**_LIBCPP_HIDE_FROM_ABI_AFTER_V1** 48 Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`) 49 when libc++ is built with an ABI version after ABI v1. This macro is used to 50 maintain ABI compatibility for symbols that have been historically exported 51 by libc++ in v1 of the ABI, but that we don't want to export in the future. 52 53 This macro works as follows. When we build libc++, we either hide the symbol 54 from the ABI (if the symbol is not part of the ABI in the version we're 55 building), or we leave it included. From user code (i.e. when we're not 56 building libc++), the macro always marks symbols as internal so that programs 57 built using new libc++ headers stop relying on symbols that are removed from 58 the ABI in a future version. Each time we release a new stable version of the 59 ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can 60 use it to start removing symbols from the ABI after that stable version. 61 62**_LIBCPP_HIDE_FROM_ABI_PER_TU** 63 This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI` 64 are local to each translation unit in addition to being local to each final 65 linked image. This macro is defined to either 0 or 1. When it is defined to 66 1, translation units compiled with different versions of libc++ can be linked 67 together, since all non ABI-facing functions are local to each translation unit. 68 This allows static archives built with different versions of libc++ to be linked 69 together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI` 70 are not guaranteed to have the same address across translation unit boundaries. 71 72 When the macro is defined to 0, there is no guarantee that translation units 73 compiled with different versions of libc++ can interoperate. However, this 74 leads to code size improvements, since non ABI-facing functions can be 75 deduplicated across translation unit boundaries. 76 77 This macro can be defined by users to control the behavior they want from 78 libc++. The default value of this macro (0 or 1) is controlled by whether 79 `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to 80 be used by vendors only (see below). 81 82**_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT** 83 This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`. 84 When the macro is defined, per TU ABI insulation is enabled by default, and 85 `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden by users. 86 Otherwise, per TU ABI insulation is disabled by default, and 87 `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden by users. 88 89 This macro is intended for vendors to control whether they want to ship 90 libc++ with per TU ABI insulation enabled by default. Users can always 91 control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU` 92 appropriately. 93 94 By default, this macro is not defined, which means that per TU ABI insulation 95 is not provided unless explicitly overridden by users. 96 97**_LIBCPP_TYPE_VIS** 98 Mark a type's typeinfo, vtable and members as having default visibility. 99 This attribute cannot be used on class templates. 100 101**_LIBCPP_TEMPLATE_VIS** 102 Mark a type's typeinfo and vtable as having default visibility. 103 This macro has no effect on the visibility of the type's member functions. 104 105 **GCC Behavior**: GCC does not support Clang's `type_visibility(...)` 106 attribute. With GCC the `visibility(...)` attribute is used and member 107 functions are affected. 108 109 **Windows Behavior**: DLLs do not support dllimport/export on class templates. 110 The macro has an empty definition on this platform. 111 112 113**_LIBCPP_ENUM_VIS** 114 Mark the typeinfo of an enum as having default visibility. This attribute 115 should be applied to all enum declarations. 116 117 **Windows Behavior**: DLLs do not support importing or exporting enumeration 118 typeinfo. The macro has an empty definition on this platform. 119 120 **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even 121 if `-fvisibility=hidden` is specified. Additionally applying a visibility 122 attribute to an enum class results in a warning. The macro has an empty 123 definition with GCC. 124 125**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS** 126 Mark the member functions, typeinfo, and vtable of the type named in 127 a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library. 128 This attribute must be specified on all extern class template declarations. 129 130 This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute 131 specified on the primary template and to export the member functions produced 132 by the explicit instantiation in the dylib. 133 134 **GCC Behavior**: GCC ignores visibility attributes applied the type in 135 extern template declarations and applying an attribute results in a warning. 136 However since `_LIBCPP_TEMPLATE_VIS` is the same as 137 `__attribute__((visibility("default"))` the visibility is already correct. 138 The macro has an empty definition with GCC. 139 140 **Windows Behavior**: `extern template` and `dllexport` are fundamentally 141 incompatible *on a class template* on Windows; the former suppresses 142 instantiation, while the latter forces it. Specifying both on the same 143 declaration makes the class template be instantiated, which is not desirable 144 inside headers. This macro therefore expands to `dllimport` outside of libc++ 145 but nothing inside of it (rather than expanding to `dllexport`); instead, the 146 explicit instantiations themselves are marked as exported. Note that this 147 applies *only* to extern *class* templates. Extern *function* templates obey 148 regular import/export semantics, and applying `dllexport` directly to the 149 extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct 150 thing to do for them. 151 152**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS** 153 Mark the member functions, typeinfo, and vtable of an explicit instantiation 154 of a class template as being exported by the libc++ library. This attribute 155 must be specified on all class template explicit instantiations. 156 157 It is only necessary to mark the explicit instantiation itself (as opposed to 158 the extern template declaration) as exported on Windows, as discussed above. 159 On all other platforms, this macro has an empty definition. 160 161**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS** 162 Mark a symbol as hidden so it will not be exported from shared libraries. This 163 is intended specifically for method templates of either classes marked with 164 `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation 165 declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`. 166 167 When building libc++ with hidden visibility, we want explicit template 168 instantiations to export members, which is consistent with existing Windows 169 behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export 170 their members, which is again consistent with existing Windows behavior. 171 Both these changes are necessary for clients to be able to link against a 172 libc++ DSO built with hidden visibility without encountering missing symbols. 173 174 An unfortunate side effect, however, is that method templates of classes 175 either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation 176 declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default 177 visibility when instantiated. These methods are often implicitly instantiated 178 inside other libraries which use the libc++ headers, and will therefore end up 179 being exported from those libraries, since those implicit instantiations will 180 receive default visibility. This is not acceptable for libraries that wish to 181 control their visibility, and led to PR30642. 182 183 Consequently, all such problematic method templates are explicitly marked 184 either hidden (via this macro) or inline, so that they don't leak into client 185 libraries. The problematic methods were found by running 186 `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_ 187 against the libc++ headers after making `_LIBCPP_TYPE_VIS` and 188 `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. 189 190**_LIBCPP_EXCEPTION_ABI** 191 Mark the member functions, typeinfo, and vtable of the type as being exported 192 by the libc++ library. This macro must be applied to all *exception types*. 193 Exception types should be defined directly in namespace `std` and not the 194 versioning namespace. This allows throwing and catching some exception types 195 between libc++ and libstdc++. 196 197**_LIBCPP_INTERNAL_LINKAGE** 198 Mark the affected entity as having internal linkage (i.e. the `static` 199 keyword in C). This is only a best effort: when the `internal_linkage` 200 attribute is not available, we fall back to forcing the function to be 201 inlined, which approximates internal linkage since an externally visible 202 symbol is never generated for that function. This is an internal macro 203 used as an implementation detail by other visibility macros. Never mark 204 a function or a class with this macro directly. 205 206**_LIBCPP_ALWAYS_INLINE** 207 Forces inlining of the function it is applied to. For visibility purposes, 208 this macro is used to make sure that an externally visible symbol is never 209 generated in an object file when the `internal_linkage` attribute is not 210 available. This is an internal macro used by other visibility macros, and 211 it should not be used directly. 212 213Links 214===== 215 216* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_ 217* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_ 218* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_ 219