1===================
2Availability Markup
3===================
4
5.. contents::
6   :local:
7
8Overview
9========
10
11Libc++ is used as a system library on macOS and iOS (amongst others). In order
12for users to be able to compile a binary that is intended to be deployed to an
13older version of the platform, clang provides the
14`availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_
15that can be placed on declarations to describe the lifecycle of a symbol in the
16library.
17
18Design
19======
20
21When a new feature is introduced that requires dylib support, a macro should be
22created in include/__config to mark this feature as unavailable for all the
23systems. 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
34When the library is updated by the platform vendor, the markup can be updated.
35For 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
43In the source code, the macro can be added on a class if the full class requires
44type 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
50or 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
55Testing
56=======
57
58Some parameters can be passed to lit to run the test-suite and exercise the
59availability.
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
69Tests 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).
100