Skip to content

Commit c81b2df

Browse files
philnik777philnik777
committed
[libc++] Move the availability documentation to a design document
1 parent e3d0ac1 commit c81b2df

File tree

3 files changed

+46
-49
lines changed

3 files changed

+46
-49
lines changed

‎libcxx/docs/DesignDocs/Availability.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
2+
====================
3+
Availability markups
4+
====================
5+
6+
Libc++ is shipped by various vendors. In particular, it is used as a system library on macOS, iOS and other Apple
7+
platforms. In order for users to be able to compile a binary that is intended to be deployed to an older version of a
8+
platform, Clang provides `availability attributes <https://clang.llvm.org/docs/AttributeReference.html#availability>`_.
9+
These attributes can be placed on declarations and are used to describe the life cycle of a symbol in the library.
10+
11+
The main goal is to ensure a compile-time error if a symbol that hasn't been introduced in a previously released library
12+
is used in a program that targets that previously released library. Normally, this would be a load-time error when one
13+
tries to launch the program against the older library.
14+
15+
For example, the filesystem library was introduced in the dylib in LLVM 9. On Apple platforms, this corresponds to
16+
macOS 10.15. If a user compiles on a macOS 10.15 host but targets macOS 10.13 with their program, the compiler would
17+
normally not complain (because the required declarations are in the headers), but the dynamic loader would fail to find
18+
the symbols when actually trying to launch the program on macOS 10.13. To turn this into a compile-time issue instead,
19+
declarations are annotated with when they were introduced, and the compiler can produce a diagnostic if the program
20+
references something that isn't available on the deployment target.
21+
22+
23+
This mechanism is general in nature, and any vendor can add their markup to the library (see below). Whenever a new
24+
feature is added that requires support in the shared library, two macros are added below to allow marking the feature as
25+
unavailable:
26+
27+
1. A macro named ``_LIBCPP_AVAILABILITY_HAS_<feature>`` which must be defined to ``_LIBCPP_INTRODUCED_IN_<version>`` for
28+
the appropriate LLVM version.
29+
30+
2. A macro named ``_LIBCPP_AVAILABILITY_<feature>``, which must be defined to ``_LIBCPP_INTRODUCED_IN_<version>_MARKUP``
31+
for the appropriate LLVM version.
32+
33+
When vendors decide to ship the feature as part of their shared library, they can update the
34+
``_LIBCPP_INTRODUCED_IN_<version>`` macro (and the markup counterpart) based on the platform version they shipped that
35+
version of LLVM in. The library will then use this markup to provide an optimal user experience on these platforms.
36+
37+
Furthermore, many features in the standard library have corresponding feature-test macros. The
38+
``_LIBCPP_AVAILABILITY_HAS_<feature>`` macros are checked by the corresponding feature-test macros generated by
39+
``generate_feature_test_macro_components.py`` to ensure that the library doesn't announce a feature as being implemented
40+
if it is unavailable on the deployment target.
41+
42+
Note that this mechanism is disabled by default in the "upstream" libc++. Availability annotations are only meaningful
43+
when shipping libc++ inside a platform (i.e. as a system library), and so vendors that want them should turn those
44+
annotations on at CMake configuration time.

‎libcxx/docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@ Design Documents
212212

213213
DesignDocs/ABIVersioning
214214
DesignDocs/AtomicDesign
215+
DesignDocs/Availability
215216
DesignDocs/CapturingConfigInfo
216217
DesignDocs/ExperimentalFeatures
217218
DesignDocs/ExtendedCXX03Support

‎libcxx/include/__configuration/availability.h‎

Lines changed: 1 addition & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -17,55 +17,7 @@
1717
# pragma GCC system_header
1818
#endif
1919

20-
// Libc++ is shipped by various vendors. In particular, it is used as a system
21-
// library on macOS, iOS and other Apple platforms. In order for users to be
22-
// able to compile a binary that is intended to be deployed to an older version
23-
// of a platform, Clang provides availability attributes [1]. These attributes
24-
// can be placed on declarations and are used to describe the life cycle of a
25-
// symbol in the library.
26-
//
27-
// The main goal is to ensure a compile-time error if a symbol that hasn't been
28-
// introduced in a previously released library is used in a program that targets
29-
// that previously released library. Normally, this would be a load-time error
30-
// when one tries to launch the program against the older library.
31-
//
32-
// For example, the filesystem library was introduced in the dylib in LLVM 9.
33-
// On Apple platforms, this corresponds to macOS 10.15. If a user compiles on
34-
// a macOS 10.15 host but targets macOS 10.13 with their program, the compiler
35-
// would normally not complain (because the required declarations are in the
36-
// headers), but the dynamic loader would fail to find the symbols when actually
37-
// trying to launch the program on macOS 10.13. To turn this into a compile-time
38-
// issue instead, declarations are annotated with when they were introduced, and
39-
// the compiler can produce a diagnostic if the program references something that
40-
// isn't available on the deployment target.
41-
//
42-
// This mechanism is general in nature, and any vendor can add their markup to
43-
// the library (see below). Whenever a new feature is added that requires support
44-
// in the shared library, two macros are added below to allow marking the feature
45-
// as unavailable:
46-
// 1. A macro named `_LIBCPP_AVAILABILITY_HAS_<feature>` which must be defined
47-
// to `_LIBCPP_INTRODUCED_IN_<version>` for the appropriate LLVM version.
48-
// 2. A macro named `_LIBCPP_AVAILABILITY_<feature>`, which must be defined to
49-
// `_LIBCPP_INTRODUCED_IN_<version>_MARKUP` for the appropriate LLVM version.
50-
//
51-
// When vendors decide to ship the feature as part of their shared library, they
52-
// can update the `_LIBCPP_INTRODUCED_IN_<version>` macro (and the markup counterpart)
53-
// based on the platform version they shipped that version of LLVM in. The library
54-
// will then use this markup to provide an optimal user experience on these platforms.
55-
//
56-
// Furthermore, many features in the standard library have corresponding
57-
// feature-test macros. The `_LIBCPP_AVAILABILITY_HAS_<feature>` macros
58-
// are checked by the corresponding feature-test macros generated by
59-
// generate_feature_test_macro_components.py to ensure that the library
60-
// doesn't announce a feature as being implemented if it is unavailable on
61-
// the deployment target.
62-
//
63-
// Note that this mechanism is disabled by default in the "upstream" libc++.
64-
// Availability annotations are only meaningful when shipping libc++ inside
65-
// a platform (i.e. as a system library), and so vendors that want them should
66-
// turn those annotations on at CMake configuration time.
67-
//
68-
// [1]: https://clang.llvm.org/docs/AttributeReference.html#availability
20+
// Documentation for this utility can be found at https://libcxx.llvm.org/DesignDocs/Availability.html
6921

7022
// Availability markup is disabled when building the library, or when a non-Clang
7123
// compiler is used because only Clang supports the necessary attributes.

0 commit comments

Comments
 (0)