diff options
Diffstat (limited to 'lib/libcxx/docs/DesignDocs')
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst | 49 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst | 2 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst | 44 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/VisibilityMacros.rst | 38 |
4 files changed, 84 insertions, 49 deletions
diff --git a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst b/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst index b8b44509790..4e6d80b50bf 100644 --- a/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst +++ b/lib/libcxx/docs/DesignDocs/AvailabilityMarkup.rst @@ -24,11 +24,11 @@ systems. For example:: // Define availability macros. #if defined(_LIBCPP_USE_AVAILABILITY_APPLE) - #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) + # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) #else if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR) - #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) - #else - #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS + # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) + #else + # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS #endif When the library is updated by the platform vendor, the markup can be updated. @@ -43,9 +43,9 @@ For example:: In the source code, the macro can be added on a class if the full class requires type info from the library for example:: - _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL - class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access - : public std::logic_error { + _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL + class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access + : public std::logic_error { or on a particular symbol: @@ -55,7 +55,7 @@ or on a particular symbol: Testing ======= -Some parameters can be passed to lit to run the test-suite and exercising the +Some parameters can be passed to lit to run the test-suite and exercise the availability. * The `platform` parameter controls the deployment target. For example lit can @@ -65,14 +65,11 @@ availability. the test-suite against the host system library. Alternatively a path to the directory containing a specific prebuilt libc++ can be used, for example: `--param=use_system_cxx_lib=/path/to/macOS/10.8/`. -* The `with_availability` boolean parameter enables the availability markup. Tests can be marked as XFAIL based on multiple features made available by lit: -* if either `use_system_cxx_lib` or `with_availability` is passed to lit, - assuming `--param=platform=macosx10.8` is passed as well the following - features will be available: +* if `--param=platform=macosx10.8` is passed, the following features will be available: - availability - availability=x86_64 @@ -81,11 +78,11 @@ Tests can be marked as XFAIL based on multiple features made available by lit: - availability=x86_64-apple-macosx10.8 - availability=macosx10.8 - This feature is used to XFAIL a test that *is* using a class of a method marked + This feature is used to XFAIL a test that *is* using a class or a method marked as unavailable *and* that is expected to *fail* if deployed on an older system. -* if `use_system_cxx_lib` is passed to lit, the following features will also - be available: +* if `use_system_cxx_lib` and `--param=platform=macosx10.8` are passed to lit, + the following features will also be available: - with_system_cxx_lib - with_system_cxx_lib=x86_64 @@ -94,21 +91,9 @@ Tests can be marked as XFAIL based on multiple features made available by lit: - with_system_cxx_lib=x86_64-apple-macosx10.8 - with_system_cxx_lib=macosx10.8 - This feature is used to XFAIL a test that is *not* using a class of a method + This feature is used to XFAIL a test that is *not* using a class or a method marked as unavailable *but* that is expected to fail if deployed on an older - system. For example if we know that it exhibits a but in the libc on a - particular system version. - -* if `with_availability` is passed to lit, the following features will also - be available: - - - availability_markup - - availability_markup=x86_64 - - availability_markup=macosx - - availability_markup=x86_64-macosx - - availability_markup=x86_64-apple-macosx10.8 - - availability_markup=macosx10.8 - - This feature is used to XFAIL a test that *is* using a class of a method - marked as unavailable *but* that is expected to *pass* if deployed on an older - system. For example if it is using a symbol in a statically evaluated context. + system. For example, if the test exhibits a bug in the libc on a particular + system version, or if the test uses a symbol that is not available on an + older version of the dylib (but for which there is no availability markup, + otherwise the XFAIL should use `availability` above). diff --git a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst index 88102251d93..29156bff8bc 100644 --- a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst +++ b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst @@ -28,7 +28,7 @@ Design Goals It makes developers lives harder if they have to regenerate the libc++ headers every time they are modified. -* The solution should not make any of the libc++ headers dependant on +* The solution should not make any of the libc++ headers dependent on files generated by the build system. The headers should be able to compile out of the box without any modification. diff --git a/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst b/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst new file mode 100644 index 00000000000..d55af96c674 --- /dev/null +++ b/lib/libcxx/docs/DesignDocs/FeatureTestMacros.rst @@ -0,0 +1,44 @@ +=================== +Feature Test Macros +=================== + +.. contents:: + :local: + +Overview +======== + +Libc++ implements the C++ feature test macros as specified in the C++2a standard, +and before that in non-normative guiding documents (`See cppreference <https://en.cppreference.com/w/User:D41D8CD98F/feature_testing_macros>`) + +Design +====== + +Feature test macros are tricky to track, implement, test, and document correctly. +They must be available from a list of headers, they may have different values in +different dialects, and they may or may not be implemented by libc++. In order to +track all of these conditions correctly and easily, we want a Single Source of +Truth (SSoT) that defines each feature test macro, its values, the headers it +lives in, and whether or not is is implemented by libc++. From this SSoA we +have enough information to automatically generate the `<version>` header, +the tests, and the documentation. + +Therefore we maintain a SSoA in +`libcxx/test/std/language.support/support.limits/support.limits.general/generate_feature_test_macro_components.py` +which doubles as a script to generate the following components: + +* The `<version>` header. +* The version tests under `support.limits.general`. +* Documentation of libc++'s implementation of each macro. + +Usage +===== + +The `generate_feature_test_macro_components.py` script is used to track and +update feature test macros in libc++. + +Whenever a feature test macro is added or changed, the table should be updated +and the script should be re-ran. The script will clobber the existing test files +and the documentation and it will generate a new `<version>` header as a +temporary file. The generated `<version>` header should be merged with the +existing one.
\ No newline at end of file diff --git a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst b/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst index ab577df1364..d0d4f0adb22 100644 --- a/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst +++ b/lib/libcxx/docs/DesignDocs/VisibilityMacros.rst @@ -22,11 +22,11 @@ Visibility Macros Mark a symbol as being exported by the libc++ library. This attribute must be applied to the declaration of all functions exported by the libc++ dylib. -**_LIBCPP_EXTERN_VIS** +**_LIBCPP_EXPORTED_FROM_ABI** Mark a symbol as being exported by the libc++ library. This attribute may - only be applied to objects defined in the libc++ library. On Windows this - macro applies `dllimport`/`dllexport` to the symbol. On all other platforms - this macro has no effect. + only be applied to objects defined in the libc++ runtime library. On Windows, + this macro applies `dllimport`/`dllexport` to the symbol, and on other + platforms it gives the symbol default visibility. **_LIBCPP_OVERRIDABLE_FUNC_VIS** Mark a symbol as being exported by the libc++ library, but allow it to be @@ -44,6 +44,21 @@ Visibility Macros Mark a function as not being part of the ABI of any final linked image that uses it. +**_LIBCPP_HIDE_FROM_ABI_AFTER_V1** + Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`) + when libc++ is built with an ABI version after ABI v1. This macro is used to + maintain ABI compatibility for symbols that have been historically exported + by libc++ in v1 of the ABI, but that we don't want to export in the future. + + This macro works as follows. When we build libc++, we either hide the symbol + from the ABI (if the symbol is not part of the ABI in the version we're + building), or we leave it included. From user code (i.e. when we're not + building libc++), the macro always marks symbols as internal so that programs + built using new libc++ headers stop relying on symbols that are removed from + the ABI in a future version. Each time we release a new stable version of the + 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 @@ -67,9 +82,9 @@ Visibility Macros **_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. + `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden 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. + `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden 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 @@ -77,7 +92,7 @@ Visibility Macros appropriately. By default, this macro is not defined, which means that per TU ABI insulation - is not provided unless explicitly overriden by users. + is not provided unless explicitly overridden by users. **_LIBCPP_TYPE_VIS** Mark a type's typeinfo, vtable and members as having default visibility. @@ -172,15 +187,6 @@ Visibility Macros against the libc++ headers after making `_LIBCPP_TYPE_VIS` and `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility. -**_LIBCPP_EXTERN_TEMPLATE_INLINE_VISIBILITY** - Mark a member function of a class template as visible and always inline. This - macro should only be applied to member functions of class templates that are - externally instantiated. It is important that these symbols are not marked - as hidden as that will prevent the dylib definition from being found. - - This macro is used to maintain ABI compatibility for symbols that have been - historically exported by the libc++ library but are now marked inline. - **_LIBCPP_EXCEPTION_ABI** Mark the member functions, typeinfo, and vtable of the type as being exported by the libc++ library. This macro must be applied to all *exception types*. |