AvailabilityMarkup.rst (3937B)
1 =================== 2 Availability Markup 3 =================== 4 5 .. contents:: 6 :local: 7 8 Overview 9 ======== 10 11 Libc++ is used as a system library on macOS and iOS (amongst others). In order 12 for users to be able to compile a binary that is intended to be deployed to an 13 older version of the platform, clang provides the 14 `availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_ 15 that can be placed on declarations to describe the lifecycle of a symbol in the 16 library. 17 18 Design 19 ====== 20 21 When a new feature is introduced that requires dylib support, a macro should be 22 created in include/__config to mark this feature as unavailable for all the 23 systems. For example:: 24 25 // Define availability macros. 26 #if defined(_LIBCPP_USE_AVAILABILITY_APPLE) 27 # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) 28 #else if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR) 29 # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable)) 30 #else 31 # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS 32 #endif 33 34 When the library is updated by the platform vendor, the markup can be updated. 35 For example:: 36 37 #define _LIBCPP_AVAILABILITY_SHARED_MUTEX \ 38 __attribute__((availability(macosx,strict,introduced=10.12))) \ 39 __attribute__((availability(ios,strict,introduced=10.0))) \ 40 __attribute__((availability(tvos,strict,introduced=10.0))) \ 41 __attribute__((availability(watchos,strict,introduced=3.0))) 42 43 In the source code, the macro can be added on a class if the full class requires 44 type info from the library for example:: 45 46 _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL 47 class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access 48 : public std::logic_error { 49 50 or on a particular symbol: 51 52 _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void operator delete(void* __p, std::size_t __sz) _NOEXCEPT; 53 54 55 Testing 56 ======= 57 58 Some parameters can be passed to lit to run the test-suite and exercise the 59 availability. 60 61 * The `platform` parameter controls the deployment target. For example lit can 62 be invoked with `--param=platform=macosx10.8`. Default is the current host. 63 * The `use_system_cxx_lib` parameter indicates to use another library than the 64 just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run 65 the test-suite against the host system library. Alternatively a path to the 66 directory containing a specific prebuilt libc++ can be used, for example: 67 `--param=use_system_cxx_lib=/path/to/macOS/10.8/`. 68 69 Tests can be marked as XFAIL based on multiple features made available by lit: 70 71 72 * if `--param=platform=macosx10.8` is passed, the following features will be available: 73 74 - availability 75 - availability=x86_64 76 - availability=macosx 77 - availability=x86_64-macosx 78 - availability=x86_64-apple-macosx10.8 79 - availability=macosx10.8 80 81 This feature is used to XFAIL a test that *is* using a class or a method marked 82 as unavailable *and* that is expected to *fail* if deployed on an older system. 83 84 * if `use_system_cxx_lib` and `--param=platform=macosx10.8` are passed to lit, 85 the following features will also be available: 86 87 - with_system_cxx_lib 88 - with_system_cxx_lib=x86_64 89 - with_system_cxx_lib=macosx 90 - with_system_cxx_lib=x86_64-macosx 91 - with_system_cxx_lib=x86_64-apple-macosx10.8 92 - with_system_cxx_lib=macosx10.8 93 94 This feature is used to XFAIL a test that is *not* using a class or a method 95 marked as unavailable *but* that is expected to fail if deployed on an older 96 system. For example, if the test exhibits a bug in the libc on a particular 97 system version, or if the test uses a symbol that is not available on an 98 older version of the dylib (but for which there is no availability markup, 99 otherwise the XFAIL should use `availability` above).