[libc++] Rework the whole availability markup implementation

[ldionne]

Summary

Currently, vendor-specific availability markup is enabled by default.
This means that even when building against trunk libc++, the headers
will by default prevent you from using some features that were not
released in the dylib on your target platform. This is a source of
frustration since people building libc++ from sources are usually not
trying to use some vendor's released dylib.

For that reason, I've been thinking for a long time that availability
annotations should be off by default, which is the primary change that
this commit enables.

In addition, it reworks the implementation to make it easier for new
vendors to add availability annotations for their platform, and it
refreshes the documentation to reflect the current state of the codebase.

Finally, a CMake configuration option is added to control whether
availability annotations should be turned on for the flavor of libc++
being created. The intent is for vendors like Apple to turn it on, and
for the upstream libc++ to leave it off (the default).

libcxx/CMakeLists.txt

option(LIBCXX_ENABLE_RANDOM_DEVICE
    supported, most of <random> will still be available, but std::random_device
    will not." ON)
 option(LIBCXX_ENABLE_LOCALIZATION
   "Whether to include support for localization in the library. Disabling
    localization can be useful when porting to platforms that don't support
    the C locale API (e.g. embedded). When localization is not supported,
    several parts of the library will be disabled: <iostream>, <regex>, <locale>
    will be completely unusable, and other parts may be only partly available." ON)
+option(LIBCXX_ENABLE_VENDOR_AVAILABILITY_ANNOTATIONS
+  "Whether to turn on vendor availability annotations on declarations that depend
+   on definitions in a shared library. By default, we assume that we're not building
+   libc++ for any specific vendor, and we disable those annotations. Vendors wishing
+   to provide compile-time errors when using features unavailable on some version of
+   the shared library they shipped should turn this on and see `include/__availability`
+   for more details." OFF)
 option(LIBCXX_TEST_GDB_PRETTY_PRINTERS "Test gdb pretty printers." OFF)
 set(LIBCXX_TEST_CONFIG "${CMAKE_CURRENT_SOURCE_DIR}/test/configs/legacy.cfg.in" CACHE STRING
     "The Lit testing configuration to use when running the tests.")
 set(LIBCXX_TEST_PARAMS "" CACHE STRING
     "A list of parameters to run the Lit test suite with.")
 
 # Benchmark options -----------------------------------------------------------
 option(LIBCXX_INCLUDE_BENCHMARKS "Build the libc++ benchmarks and their dependencies" ON)

 config_define_if(LIBCXX_HAS_EXTERNAL_THREAD_API _LIBCPP_HAS_THREAD_API_EXTERNAL)
 config_define_if(LIBCXX_HAS_WIN32_THREAD_API _LIBCPP_HAS_THREAD_API_WIN32)
 config_define_if(LIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL)
 config_define_if(LIBCXX_HAS_MUSL_LIBC _LIBCPP_HAS_MUSL_LIBC)
 config_define_if(LIBCXX_NO_VCRUNTIME _LIBCPP_NO_VCRUNTIME)
 config_define_if(LIBCXX_ENABLE_PARALLEL_ALGORITHMS _LIBCPP_HAS_PARALLEL_ALGORITHMS)
 config_define_if_not(LIBCXX_ENABLE_RANDOM_DEVICE _LIBCPP_HAS_NO_RANDOM_DEVICE)
 config_define_if_not(LIBCXX_ENABLE_LOCALIZATION _LIBCPP_HAS_NO_LOCALIZATION)
+config_define_if_not(LIBCXX_ENABLE_VENDOR_AVAILABILITY_ANNOTATIONS _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
 
 if (LIBCXX_ABI_DEFINES)
   set(abi_defines)
   foreach (abi_define ${LIBCXX_ABI_DEFINES})
     if (NOT abi_define MATCHES "^_LIBCPP_ABI_")
       message(SEND_ERROR "Invalid ABI macro ${abi_define} in LIBCXX_ABI_DEFINES")
     endif()
     list(APPEND abi_defines "#define ${abi_define}")

libcxx/cmake/caches/Apple.cmake

 set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "")
 set(CMAKE_POSITION_INDEPENDENT_CODE OFF CACHE BOOL "")
 
 set(LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
 set(LIBCXX_ENABLE_ASSERTIONS OFF CACHE BOOL "")
 set(LIBCXX_ABI_VERSION "1" CACHE STRING "")
 set(LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY OFF CACHE BOOL "")
 set(LIBCXX_ENABLE_STATIC OFF CACHE BOOL "")
 set(LIBCXX_ENABLE_SHARED ON CACHE BOOL "")
 set(LIBCXX_TYPEINFO_COMPARISON_IMPLEMENTATION "1" CACHE STRING "")
 set(LIBCXX_CXX_ABI libcxxabi CACHE STRING "")
 set(LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT ON CACHE BOOL "")
 set(LIBCXX_ENABLE_DEBUG_MODE_SUPPORT OFF CACHE BOOL "")
+set(LIBCXX_ENABLE_VENDOR_AVAILABILITY_ANNOTATIONS ON CACHE BOOL "")
 
 set(LIBCXXABI_ENABLE_PIC OFF CACHE BOOL "")
 set(LIBCXXABI_ENABLE_ASSERTIONS OFF CACHE BOOL "")
 set(LIBCXXABI_ENABLE_FORGIVING_DYNAMIC_CAST ON CACHE BOOL "")

libcxx/docs/DesignDocs/AvailabilityMarkup.rst

-===================
-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;
-
-Furthermore, a lit feature should be added to match that availability macro,
-so that tests depending on that feature can be marked to XFAIL if the feature
-is not supported. This way, the test suite will work on platforms that have
-not shipped the feature yet. This can be done by adding the appropriate lit
-feature in test/config.py.
-
-
-Testing
-=======
-
-Some parameters can be passed to lit to run the test-suite and exercise the
-availability.
-
-* The `target_triple` parameter controls the deployment target. For example lit
-  can be invoked with `--param=target_triple=x86_64-apple-macosx10.12`.
-  Default is the current host.
-* The `use_system_cxx_lib` parameter indicates that the test suite is being
-  compiled with the intent of being run against the system library for the
-  given triple, AND that it is being run against it.
-
-Tests can be marked as XFAIL based on multiple features made available by lit.
-If `use_system_cxx_lib` is true, then assuming `target_triple=x86_64-apple-macosx10.12`,
-the following features will be made available:
-
-  - with_system_cxx_lib=macosx
-  - with_system_cxx_lib=macosx10.12
-  - with_system_cxx_lib=x86_64-apple-macosx10.12
-
-These features are used to XFAIL a test that fails when deployed on (or is
-compiled for) an older system. For example, if the test exhibits a bug in the
-libc on a particular system version, or if the test uses a symbol that is not
-available on an older version of the dylib, it can be marked as XFAIL with
-one of the above features.
-
-It is sometimes useful to check that a test fails specifically when compiled
-for a given deployment target. For example, this is the case when testing
-availability markup, where we want to make sure that using the annotated
-facility on a deployment target that doesn't support it will fail at compile
-time, not at runtime. This can be achieved by creating a `.compile.pass.cpp`
-and XFAILing it for the right deployment target. If the test doesn't fail at
-compile-time like it's supposed to, the test will XPASS. Another option is to
-create a `.verify.cpp` test that checks for the right errors, and mark that
-test as requiring `with_system_cxx_lib=<something>`.

libcxx/include/CMakeLists.txt

 set(files
+  __availability
   __bit_reference
   __bsd_locale_defaults.h
   __bsd_locale_fallbacks.h
   __debug
   __errc
   __functional_03
   __functional_base
   __functional_base_03

libcxx/include/__availability

+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP___AVAILABILITY
+#define _LIBCPP___AVAILABILITY
+
+#include <__config>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#   pragma GCC system_header
+#endif
+
+// Libc++ is shipped by various vendors. In particular, it is used as a system
+// library on macOS, iOS and other Apple platforms. In order for users to be
+// able to compile a binary that is intended to be deployed to an older version
+// of a platform, Clang provides availability attributes [1]. These attributes
+// can be placed on declarations and are used to describe the life cycle of a
+// symbol in the library.
+//
+// The main goal is to ensure a compile-time error if a symbol that hasn't been
+// introduced in a previously released library is used in a program that targets
+// that previously released library. Normally, this would be a load-time error
+// when one tries to launch the program against the older library.
+//
+// For example, the filesystem library was introduced in the dylib in macOS 10.15.
+// If a user compiles on a macOS 10.15 host but targets macOS 10.13 with their
+// program, the compiler would normally not complain (because the required
+// declarations are in the headers), but the dynamic loader would fail to find
+// the symbols when actually trying to launch the program on macOS 10.13. To
+// turn this into a compile-time issue instead, declarations are annotated with
+// when they were introduced, and the compiler can produce a diagnostic if the
+// program references something that isn't available on the deployment target.
+//
+// This mechanism is general in nature, and any vendor can add their markup to
+// the library (see below). Whenever a new feature is added that requires support
+// in the shared library, a macro should be added below to mark this feature
+// as unavailable. When vendors decide to ship the feature as part of their
+// shared library, they can update the markup appropriately.
+//
+// Note that this mechanism is disabled by default in the "upstream" libc++.
+// Availability annotations are only meaningful when shipping libc++ inside
+// a platform (i.e. as a system library), and so vendors that want them should
+// turn those annotations on at CMake configuration time.
+//
+// [1]: https://clang.llvm.org/docs/AttributeReference.html#availability
+
+
+// For backwards compatibility, allow users to define _LIBCPP_DISABLE_AVAILABILITY
+// for a while.
+#if defined(_LIBCPP_DISABLE_AVAILABILITY)
+#   if !defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
+#       define _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
+#   endif
+#endif
+
+// Availability markup is disabled when building the library, or when the compiler
+// doesn't support the proper attributes.
+#if defined(_LIBCPP_BUILDING_LIBRARY) ||                                        \
+    defined(_LIBCXXABI_BUILDING_LIBRARY) ||                                     \
+    !__has_feature(attribute_availability_with_strict) ||                       \
+    !__has_feature(attribute_availability_in_templates) ||                      \
+    !__has_extension(pragma_clang_attribute_external_declaration)
+#   if !defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
+#       define _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
+#   endif
+#endif
+
+#if defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
+
+    // This controls the availability of std::shared_mutex and std::shared_timed_mutex,
+    // which were added to the dylib later.
+#   define _LIBCPP_AVAILABILITY_SHARED_MUTEX
+
+    // These macros control the availability of std::bad_optional_access and
+    // other exception types. These were put in the shared library to prevent
+    // code bloat from every user program defining the vtable for these exception
+    // types.
+#   define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+#   define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
+#   define _LIBCPP_AVAILABILITY_BAD_ANY_CAST
+
+    // This controls the availability of std::uncaught_exceptions().
+#   define _LIBCPP_AVAILABILITY_UNCAUGHT_EXCEPTIONS
+
+    // This controls the availability of the sized version of ::operator delete,
+    // which was added to the dylib later.
+#   define _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE
+
+    // This controls the availability of the std::future_error exception.
+#   define _LIBCPP_AVAILABILITY_FUTURE_ERROR
+
+    // This controls the availability of std::type_info's vtable.
+    // I can't imagine how using std::type_info can work at all if
+    // this isn't supported.
+#   define _LIBCPP_AVAILABILITY_TYPEINFO_VTABLE
+
+    // This controls the availability of std::locale::category members
+    // (e.g. std::locale::collate), which are defined in the dylib.
+#   define _LIBCPP_AVAILABILITY_LOCALE_CATEGORY
+
+    // This controls the availability of atomic operations on std::shared_ptr
+    // (e.g. `std::atomic_store(std::shared_ptr)`), which require a shared
+    // lock table located in the dylib.
+#   define _LIBCPP_AVAILABILITY_ATOMIC_SHARED_PTR
+
+    // These macros control the availability of all parts of <filesystem> that
+    // depend on something in the dylib.
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM_PUSH
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM_POP
+
+    // This controls the availability of std::to_chars.
+#   define _LIBCPP_AVAILABILITY_TO_CHARS
+
+    // This controls the availability of the C++20 synchronization library,
+    // which requires shared library support for various operations
+    // (see libcxx/src/atomic.cpp).
+#   define _LIBCPP_AVAILABILITY_SYNC
+
+#elif defined(__APPLE__)
+
+#   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)))
+#   define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS                             \
+        __attribute__((availability(macosx,strict,introduced=10.13)))           \
+        __attribute__((availability(ios,strict,introduced=11.0)))               \
+        __attribute__((availability(tvos,strict,introduced=11.0)))              \
+        __attribute__((availability(watchos,strict,introduced=4.0)))
+#   define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS                              \
+        _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+#   define _LIBCPP_AVAILABILITY_BAD_ANY_CAST                                    \
+        _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+#   define _LIBCPP_AVAILABILITY_UNCAUGHT_EXCEPTIONS                             \
+        __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)))
+#   define _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE                                \
+        __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)))
+#   define _LIBCPP_AVAILABILITY_FUTURE_ERROR                                    \
+        __attribute__((availability(ios,strict,introduced=6.0)))
+#   define _LIBCPP_AVAILABILITY_TYPEINFO_VTABLE                                 \
+        __attribute__((availability(macosx,strict,introduced=10.9)))            \
+        __attribute__((availability(ios,strict,introduced=7.0)))
+#   define _LIBCPP_AVAILABILITY_LOCALE_CATEGORY                                 \
+        __attribute__((availability(macosx,strict,introduced=10.9)))            \
+        __attribute__((availability(ios,strict,introduced=7.0)))
+#   define _LIBCPP_AVAILABILITY_ATOMIC_SHARED_PTR                               \
+        __attribute__((availability(macosx,strict,introduced=10.9)))            \
+        __attribute__((availability(ios,strict,introduced=7.0)))
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM                                      \
+        __attribute__((availability(macosx,strict,introduced=10.15)))           \
+        __attribute__((availability(ios,strict,introduced=13.0)))               \
+        __attribute__((availability(tvos,strict,introduced=13.0)))              \
+        __attribute__((availability(watchos,strict,introduced=6.0)))
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM_PUSH                                 \
+        _Pragma("clang attribute push(__attribute__((availability(macosx,strict,introduced=10.15))), apply_to=any(function,record))") \
+        _Pragma("clang attribute push(__attribute__((availability(ios,strict,introduced=13.0))), apply_to=any(function,record))")     \
+        _Pragma("clang attribute push(__attribute__((availability(tvos,strict,introduced=13.0))), apply_to=any(function,record))")    \
+        _Pragma("clang attribute push(__attribute__((availability(watchos,strict,introduced=6.0))), apply_to=any(function,record))")
+#   define _LIBCPP_AVAILABILITY_FILESYSTEM_POP                                  \
+        _Pragma("clang attribute pop")                                          \
+        _Pragma("clang attribute pop")                                          \
+        _Pragma("clang attribute pop")                                          \
+        _Pragma("clang attribute pop")
+#   define _LIBCPP_AVAILABILITY_TO_CHARS                                        \
+        _LIBCPP_AVAILABILITY_FILESYSTEM
+#   define _LIBCPP_AVAILABILITY_SYNC                                            \
+        __attribute__((unavailable))
+
+#else
+
+// ...New vendors can add availability markup here...
+
+#   error "It looks like you're trying to enable vendor availability markup, but you haven't defined the corresponding macros yet!"
+
+#endif
+
+// Define availability attributes that depend on _LIBCPP_NO_EXCEPTIONS.
+// Those are defined in terms of the availability attributes above, and
+// should not be vendor-specific.
+#if defined(_LIBCPP_NO_EXCEPTIONS)
+#   define _LIBCPP_AVAILABILITY_FUTURE
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS
+#else
+#   define _LIBCPP_AVAILABILITY_FUTURE                    _LIBCPP_AVAILABILITY_FUTURE_ERROR
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST        _LIBCPP_AVAILABILITY_BAD_ANY_CAST
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+#   define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS  _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
+#endif
+
+#endif  // _LIBCPP___AVAILABILITY

libcxx/include/__config

 #if !defined(__cpp_coroutines) || __cpp_coroutines < 201703L
 #define _LIBCPP_HAS_NO_COROUTINES
 #endif
 
 #if !defined(__cpp_impl_three_way_comparison) || __cpp_impl_three_way_comparison < 201907L
 #define _LIBCPP_HAS_NO_SPACESHIP_OPERATOR
 #endif
 
-// Decide whether to use availability macros.
-#if !defined(_LIBCPP_BUILDING_LIBRARY) &&                                      \
-    !defined(_LIBCXXABI_BUILDING_LIBRARY) &&                                   \
-    !defined(_LIBCPP_DISABLE_AVAILABILITY) &&                                  \
-    __has_feature(attribute_availability_with_strict) &&                       \
-    __has_feature(attribute_availability_in_templates) &&                      \
-    __has_extension(pragma_clang_attribute_external_declaration)
-#  ifdef __APPLE__
-#    define _LIBCPP_USE_AVAILABILITY_APPLE
-#  endif
-#endif
-
-// Define availability macros.
-#if defined(_LIBCPP_USE_AVAILABILITY_APPLE)
-#  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)))
-#  define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS                             \
-     __attribute__((availability(macosx,strict,introduced=10.13)))             \
-     __attribute__((availability(ios,strict,introduced=11.0)))                 \
-     __attribute__((availability(tvos,strict,introduced=11.0)))                \
-     __attribute__((availability(watchos,strict,introduced=4.0)))
-#  define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS                              \
-     _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
-#  define _LIBCPP_AVAILABILITY_BAD_ANY_CAST                                    \
-     _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
-#  define _LIBCPP_AVAILABILITY_UNCAUGHT_EXCEPTIONS                             \
-     __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)))
-#  define _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE                                \
-     __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)))
-#  define _LIBCPP_AVAILABILITY_FUTURE_ERROR                                    \
-     __attribute__((availability(ios,strict,introduced=6.0)))
-#  define _LIBCPP_AVAILABILITY_TYPEINFO_VTABLE                                 \
-     __attribute__((availability(macosx,strict,introduced=10.9)))              \
-     __attribute__((availability(ios,strict,introduced=7.0)))
-#  define _LIBCPP_AVAILABILITY_LOCALE_CATEGORY                                 \
-     __attribute__((availability(macosx,strict,introduced=10.9)))              \
-     __attribute__((availability(ios,strict,introduced=7.0)))
-#  define _LIBCPP_AVAILABILITY_ATOMIC_SHARED_PTR                               \
-     __attribute__((availability(macosx,strict,introduced=10.9)))              \
-     __attribute__((availability(ios,strict,introduced=7.0)))
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM                                      \
-     __attribute__((availability(macosx,strict,introduced=10.15)))             \
-     __attribute__((availability(ios,strict,introduced=13.0)))                 \
-     __attribute__((availability(tvos,strict,introduced=13.0)))                \
-     __attribute__((availability(watchos,strict,introduced=6.0)))
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM_PUSH                                 \
-     _Pragma("clang attribute push(__attribute__((availability(macosx,strict,introduced=10.15))), apply_to=any(function,record))") \
-     _Pragma("clang attribute push(__attribute__((availability(ios,strict,introduced=13.0))), apply_to=any(function,record))")     \
-     _Pragma("clang attribute push(__attribute__((availability(tvos,strict,introduced=13.0))), apply_to=any(function,record))")    \
-     _Pragma("clang attribute push(__attribute__((availability(watchos,strict,introduced=6.0))), apply_to=any(function,record))")
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM_POP                                  \
-     _Pragma("clang attribute pop")                                            \
-     _Pragma("clang attribute pop")                                            \
-     _Pragma("clang attribute pop")                                            \
-     _Pragma("clang attribute pop")
-#  define _LIBCPP_AVAILABILITY_TO_CHARS                                        \
-     _LIBCPP_AVAILABILITY_FILESYSTEM
-#  define _LIBCPP_AVAILABILITY_SYNC                                            \
-     __attribute__((unavailable))
-#else
-#  define _LIBCPP_AVAILABILITY_SHARED_MUTEX
-#  define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
-#  define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
-#  define _LIBCPP_AVAILABILITY_BAD_ANY_CAST
-#  define _LIBCPP_AVAILABILITY_UNCAUGHT_EXCEPTIONS
-#  define _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE
-#  define _LIBCPP_AVAILABILITY_FUTURE_ERROR
-#  define _LIBCPP_AVAILABILITY_TYPEINFO_VTABLE
-#  define _LIBCPP_AVAILABILITY_LOCALE_CATEGORY
-#  define _LIBCPP_AVAILABILITY_ATOMIC_SHARED_PTR
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM_PUSH
-#  define _LIBCPP_AVAILABILITY_FILESYSTEM_POP
-#  define _LIBCPP_AVAILABILITY_TO_CHARS
-#  define _LIBCPP_AVAILABILITY_SYNC
-#endif
-
-// Define availability that depends on _LIBCPP_NO_EXCEPTIONS.
-#ifdef _LIBCPP_NO_EXCEPTIONS
-#  define _LIBCPP_AVAILABILITY_FUTURE
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS
-#else
-#  define _LIBCPP_AVAILABILITY_FUTURE                    _LIBCPP_AVAILABILITY_FUTURE_ERROR
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST        _LIBCPP_AVAILABILITY_BAD_ANY_CAST
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
-#  define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS  _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
-#endif
-
 #if defined(_LIBCPP_COMPILER_IBM)
 #define _LIBCPP_HAS_NO_PRAGMA_PUSH_POP_MACRO
 #endif
 
 #if defined(_LIBCPP_HAS_NO_PRAGMA_PUSH_POP_MACRO)
 #  define _LIBCPP_PUSH_MACROS
 #  define _LIBCPP_POP_MACROS
 #else

libcxx/include/__config_site.in

 #cmakedefine _LIBCPP_HAS_NO_MONOTONIC_CLOCK
 #cmakedefine _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS
 #cmakedefine _LIBCPP_HAS_MUSL_LIBC
 #cmakedefine _LIBCPP_HAS_THREAD_API_PTHREAD
 #cmakedefine _LIBCPP_HAS_THREAD_API_EXTERNAL
 #cmakedefine _LIBCPP_HAS_THREAD_API_WIN32
 #cmakedefine _LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL
 #cmakedefine _LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS
+#cmakedefine _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
 #cmakedefine _LIBCPP_NO_VCRUNTIME
 #ifndef _LIBCPP_TYPEINFO_COMPARISON_IMPLEMENTATION
 #cmakedefine _LIBCPP_TYPEINFO_COMPARISON_IMPLEMENTATION @_LIBCPP_TYPEINFO_COMPARISON_IMPLEMENTATION@
 #endif
 #cmakedefine _LIBCPP_ABI_NAMESPACE @_LIBCPP_ABI_NAMESPACE@
 #cmakedefine _LIBCPP_HAS_PARALLEL_ALGORITHMS
 #cmakedefine _LIBCPP_HAS_NO_RANDOM_DEVICE
 #cmakedefine _LIBCPP_HAS_NO_LOCALIZATION
 
 @_LIBCPP_ABI_DEFINES@
 
 #endif // _LIBCPP_CONFIG_SITE

libcxx/include/__locale

 // -*- C++ -*-
 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___LOCALE
 #define _LIBCPP___LOCALE
 
 #include <__config>
+#include <__availability>
 #include <string>
 #include <memory>
 #include <utility>
 #include <mutex>
 #include <cstdint>
 #include <cctype>
 #include <locale.h>
 #if defined(_LIBCPP_MSVCRT_LIKE)

libcxx/include/__threading_support

 // -*- C++ -*-
 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP_THREADING_SUPPORT
 #define _LIBCPP_THREADING_SUPPORT
 
 #include <__config>
+#include <__availability>
 #include <chrono>
 #include <iosfwd>
 #include <errno.h>
 
 #ifndef _LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER
 #pragma GCC system_header
 #endif
 

libcxx/include/any

namespace std {
   template<class ValueType>
     ValueType* any_cast(any* operand) noexcept;
 
 } // namespace std
 
 */
 
 #include <experimental/__config>
+#include <__availability>
 #include <memory>
 #include <typeinfo>
 #include <type_traits>
 #include <cstdlib>
 #include <version>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header

libcxx/include/atomic

 
 #define ATOMIC_FLAG_INIT see below
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <__threading_support>
 #include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <type_traits>
 #include <version>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)

libcxx/include/barrier

private:
     CompletionFunction completion; // exposition only
   };
 
 }
 
 */
 
 #include <__config>
+#include <__availability>
 #include <atomic>
 #ifndef _LIBCPP_HAS_NO_TREE_BARRIER
 # include <memory>
 #endif
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header
 #endif

libcxx/include/charconv

from_chars_result from_chars(const char* first, const char* last,
                                long double& value,
                                chars_format fmt = chars_format::general);
 
 } // namespace std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <__errc>
 #include <type_traits>
 #include <limits>
 #include <stdint.h>
 #include <string.h>
 #include <math.h>
 
 #include <__debug>

libcxx/include/chrono

 constexpr chrono::year                                  operator ""y(unsigned long long y) noexcept; // C++20
 }  // chrono_literals
 }  // literals
 
 }  // std
 */
 
 #include <__config>
+#include <__availability>
 #include <ctime>
 #include <type_traits>
 #include <ratio>
 #include <limits>
 #include <version>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header

libcxx/include/exception

 template <class T> [[noreturn]] void throw_with_nested(T&& t);
 template <class E> void rethrow_if_nested(const E& e);
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <cstddef>
 #include <cstdlib>
 #include <type_traits>
 #include <version>
 
 #if defined(_LIBCPP_ABI_VCRUNTIME)
 #include <vcruntime_exception.h>
 #endif

libcxx/include/filesystem

/*
     path weakly_canonical(path const& p, error_code& ec);
 
 
 } }  // namespaces std::filesystem
 
 */
 
 #include <__config>
+#include <__availability>
 #include <cstddef>
 #include <cstdlib>
 #include <chrono>
 #include <iterator>
 #include <iosfwd>
 #include <memory>
 #include <stack>
 #include <string>

libcxx/include/fstream

 typedef basic_fstream<char>    fstream;
 typedef basic_fstream<wchar_t> wfstream;
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <ostream>
 #include <istream>
 #include <__locale>
 #include <cstdio>
 #include <cstdlib>
 #include <filesystem>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)

libcxx/include/future

 
 template <class R, class Alloc> struct uses_allocator<packaged_task<R>, Alloc>;
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <system_error>
 #include <memory>
 #include <chrono>
 #include <exception>
 #include <mutex>
 #include <thread>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)

libcxx/include/latch

private:
     ptrdiff_t __counter; // exposition only
   };
 
 }
 
 */
 
 #include <__config>
+#include <__availability>
 #include <atomic>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header
 #endif
 
 #ifdef _LIBCPP_HAS_NO_THREADS
 # error <latch> is not supported on this single threaded system

libcxx/include/memory

 
 void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <type_traits>
 #include <typeinfo>
 #include <cstddef>
 #include <cstdint>
 #include <new>
 #include <utility>
 #include <limits>
 #include <iterator>

libcxx/include/new

 void* operator new  (std::size_t size, void* ptr) noexcept;             // nodiscard in C++2a
 void* operator new[](std::size_t size, void* ptr) noexcept;             // nodiscard in C++2a
 void  operator delete  (void* ptr, void*) noexcept;
 void  operator delete[](void* ptr, void*) noexcept;
 
 */
 
 #include <__config>
+#include <__availability>
 #include <exception>
 #include <type_traits>
 #include <cstddef>
 #include <version>
 #ifdef _LIBCPP_NO_EXCEPTIONS
 #include <cstdlib>
 #endif
 

libcxx/include/optional

 template<class T>
   optional(T) -> optional<T>;
 
 } // namespace std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <__debug>
 #include <__functional_base>
 #include <functional>
 #include <initializer_list>
 #include <new>
 #include <stdexcept>
 #include <type_traits>
 #include <utility>

libcxx/include/semaphore

 
 using binary_semaphore = counting_semaphore<1>;
 
 }
 
 */
 
 #include <__config>
+#include <__availability>
 #include <__threading_support>
 #include <atomic>
 #include <cassert>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header
 #endif
 

libcxx/include/shared_mutex

 template <class Mutex>
     void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <version>
 
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
 
 #if _LIBCPP_STD_VER > 11 || defined(_LIBCPP_BUILDING_LIBRARY)
 

libcxx/include/typeinfo

public:
     virtual const char* what() const noexcept;
 };
 
 }  // std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <exception>
 #include <cstddef>
 #include <cstdint>
 #include <type_traits>
 #ifdef _LIBCPP_NO_EXCEPTIONS
 #include <cstdlib>
 #endif
 

libcxx/include/variant

namespace std {
   template <class... Types> struct hash<variant<Types...>>;
   template <> struct hash<monostate>;
 
 } // namespace std
 
 */
 
 #include <__config>
+#include <__availability>
 #include <__tuple>
 #include <array>
 #include <exception>
 #include <functional>
 #include <initializer_list>
 #include <new>
 #include <tuple>
 #include <type_traits>

libcxx/src/optional.cpp

 //===------------------------ optional.cpp --------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "optional"
+#include "__availability"
 
 namespace std
 {
 
 bad_optional_access::~bad_optional_access() _NOEXCEPT = default;
 
 const char* bad_optional_access::what() const _NOEXCEPT {
   return "bad_optional_access";

libcxx/utils/libcxx/test/features.py

DEFAULT_FEATURES += [
   Feature(name='netbsd', when=lambda cfg: '__NetBSD__' in compilerMacros(cfg))
 ]
 
 
 # When vendor-specific availability annotations are enabled, add Lit features
 # with various forms of the target triple to make it easier to write XFAIL or
 # UNSUPPORTED markup for tests that are known to fail on a particular triple.
 #
+# More specifically, when the `use_system_cxx_lib` parameter is enabled, then
+# assuming the `target_triple` is set to `x86_64-apple-macosx10.12`, the
+# following features will be made available:
+#   - with_system_cxx_lib=macosx
+#   - with_system_cxx_lib=macosx10.12
+#   - with_system_cxx_lib=x86_64-apple-macosx10.12
+#
+# These features can be used to XFAIL a test that fails when deployed on (or is
+# compiled for) an older system. For example, if the test exhibits a bug in the
+# libc on a particular system version, or if the test uses a symbol that is not
+# available on an older version of the dylib, it can be marked as XFAIL with
+# one of the above features.
+#
+# It is sometimes useful to check that a test fails specifically when compiled
+# for a given deployment target. For example, this is the case when testing
+# availability markup, where we want to make sure that using the annotated
+# facility on a deployment target that doesn't support it will fail at compile
+# time, not at runtime. This can be achieved by creating a `.compile.pass.cpp`
+# and XFAILing it for the right deployment target. If the test doesn't fail at
+# compile-time like it's supposed to, the test will XPASS. Another option is to
+# create a `.verify.cpp` test that checks for the right errors, and mark that
+# test as requiring `with_system_cxx_lib=<something>`.
+#
 # TODO: This is very unclean -- we assume that the 'use_system_cxx_lib' parameter
 #       is set before this feature gets detected, and we also set a dummy name
 #       for the main feature. We also take for granted that `target_triple`
 #       exists in the config object. This should be refactored so that the
 #       'use_system_cxx_lib' Parameter can set these features itself.
 def _addSystemCxxLibDeclinations(cfg):
   (arch, vendor, platform) = cfg.target_triple.split('-', 2)
   (sysname, version) = re.match(r'([^0-9]+)([0-9\.]*)', platform).groups()

libcxx/utils/libcxx/test/params.py

DEFAULT_PARAMETERS = [
   Parameter(name='use_system_cxx_lib', choices=[True, False], type=bool, default=False,
             help="Whether the test suite is being *run* against the library shipped on "
                  "the target triple in use, as opposed to the trunk library.",
             actions=lambda useSystem: [
               # TODO: Remove this, see comment in features.py
               AddFeature('use_system_cxx_lib')
             ] if useSystem else [
               # If we're testing upstream libc++, disable availability markup,
-              # which is not relevant for non-shipped flabors of libc++.
+              # which is not relevant for non-shipped flavors of libc++.
               AddCompileFlag('-D_LIBCPP_DISABLE_AVAILABILITY')
             ]),
 
   # Parameters to enable or disable parts of the test suite
   Parameter(name='enable_filesystem', choices=[True, False], type=bool, default=True,
             help="Whether to enable tests for the C++ <filesystem> library.",
             actions=lambda filesystem: [] if filesystem else [
               AddFeature('c++filesystem-disabled')