// -*- 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 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