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 exercising the 59 availability. 60 61 * The `platform` parameter controls the deployement 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 * The `with_availability` boolean parameter enables the availability markup. 69 70 Tests can be marked as XFAIL based on multiple features made available by lit: 71 72 73 * if either `use_system_cxx_lib` or `with_availability` is passed to lit, 74 assuming `--param=platform=macosx10.8` is passed as well the following 75 features will be available: 76 77 - availability 78 - availability=x86_64 79 - availability=macosx 80 - availability=x86_64-macosx 81 - availability=x86_64-apple-macosx10.8 82 - availability=macosx10.8 83 84 This feature is used to XFAIL a test that *is* using a class of a method marked 85 as unavailable *and* that is expected to *fail* if deployed on an older system. 86 87 * if `use_system_cxx_lib` is passed to lit, the following features will also 88 be available: 89 90 - with_system_cxx_lib 91 - with_system_cxx_lib=x86_64 92 - with_system_cxx_lib=macosx 93 - with_system_cxx_lib=x86_64-macosx 94 - with_system_cxx_lib=x86_64-apple-macosx10.8 95 - with_system_cxx_lib=macosx10.8 96 97 This feature is used to XFAIL a test that is *not* using a class of a method 98 marked as unavailable *but* that is expected to fail if deployed on an older 99 system. For example if we know that it exhibits a but in the libc on a 100 particular system version. 101 102 * if `with_availability` is passed to lit, the following features will also 103 be available: 104 105 - availability_markup 106 - availability_markup=x86_64 107 - availability_markup=macosx 108 - availability_markup=x86_64-macosx 109 - availability_markup=x86_64-apple-macosx10.8 110 - availability_markup=macosx10.8 111 112 This feature is used to XFAIL a test that *is* using a class of a method 113 marked as unavailable *but* that is expected to *pass* if deployed on an older 114 system. For example if it is using a symbol in a statically evaluated context. 115
