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