diff options
Diffstat (limited to 'libcxx/docs')
| -rw-r--r-- | libcxx/docs/BuildingLibcxx.rst | 9 | ||||
| -rw-r--r-- | libcxx/docs/DesignDocs/VisibilityMacros.rst | 39 |
2 files changed, 45 insertions, 3 deletions
diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst index d0b03c675c8..daf9229a0d0 100644 --- a/libcxx/docs/BuildingLibcxx.rst +++ b/libcxx/docs/BuildingLibcxx.rst @@ -332,6 +332,15 @@ libc++ Feature Options Use the specified GCC toolchain and standard library when building the native stdlib benchmark tests. +.. option:: LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL + + **Default**: ``OFF`` + + Pick the default for whether to constrain ABI-unstable symbols to + each individual translation unit. This setting controls whether + `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined by default -- + see the documentation of that macro for details. + libc++ ABI Feature Options -------------------------- diff --git a/libcxx/docs/DesignDocs/VisibilityMacros.rst b/libcxx/docs/DesignDocs/VisibilityMacros.rst index 493b445750e..9a757ff53f3 100644 --- a/libcxx/docs/DesignDocs/VisibilityMacros.rst +++ b/libcxx/docs/DesignDocs/VisibilityMacros.rst @@ -42,9 +42,7 @@ Visibility Macros **_LIBCPP_HIDE_FROM_ABI** Mark a function as not being part of the ABI of any final linked image that - uses it, and also as being internal to each TU that uses that function. In - other words, the address of a function marked with this attribute is not - guaranteed to be the same across translation units. + uses it. **_LIBCPP_HIDE_FROM_ABI_AFTER_V1** Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`) @@ -61,6 +59,41 @@ Visibility Macros ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can use it to start removing symbols from the ABI after that stable version. +**_LIBCPP_HIDE_FROM_ABI_PER_TU** + This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI` + are local to each translation unit in addition to being local to each final + linked image. This macro is defined to either 0 or 1. When it is defined to + 1, translation units compiled with different versions of libc++ can be linked + together, since all non ABI-facing functions are local to each translation unit. + This allows static archives built with different versions of libc++ to be linked + together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI` + are not guaranteed to have the same address across translation unit boundaries. + + When the macro is defined to 0, there is no guarantee that translation units + compiled with different versions of libc++ can interoperate. However, this + leads to code size improvements, since non ABI-facing functions can be + deduplicated across translation unit boundaries. + + This macro can be defined by users to control the behavior they want from + libc++. The default value of this macro (0 or 1) is controlled by whether + `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to + be used by vendors only (see below). + +**_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT** + This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`. + When the macro is defined, per TU ABI insulation is enabled by default, and + `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overriden by users. + Otherwise, per TU ABI insulation is disabled by default, and + `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overriden by users. + + This macro is intended for vendors to control whether they want to ship + libc++ with per TU ABI insulation enabled by default. Users can always + control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU` + appropriately. + + By default, this macro is not defined, which means that per TU ABI insulation + is not provided unless explicitly overriden by users. + **_LIBCPP_TYPE_VIS** Mark a type's typeinfo, vtable and members as having default visibility. This attribute cannot be used on class templates. |
