libcxx/include/__availability

   1 // -*- C++ -*-
   2 //===----------------------------------------------------------------------===//
   3 //
   4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef _LIBCPP___AVAILABILITY
  11 #define _LIBCPP___AVAILABILITY
  12
  13 #include <__config>
  14
  15 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
  16 #  pragma GCC system_header
  17 #endif
  18
  19 // Libc++ is shipped by various vendors. In particular, it is used as a system
  20 // library on macOS, iOS and other Apple platforms. In order for users to be
  21 // able to compile a binary that is intended to be deployed to an older version
  22 // of a platform, Clang provides availability attributes [1]. These attributes
  23 // can be placed on declarations and are used to describe the life cycle of a
  24 // symbol in the library.
  25 //
  26 // The main goal is to ensure a compile-time error if a symbol that hasn't been
  27 // introduced in a previously released library is used in a program that targets
  28 // that previously released library. Normally, this would be a load-time error
  29 // when one tries to launch the program against the older library.
  30 //
  31 // For example, the filesystem library was introduced in the dylib in macOS 10.15.
  32 // If a user compiles on a macOS 10.15 host but targets macOS 10.13 with their
  33 // program, the compiler would normally not complain (because the required
  34 // declarations are in the headers), but the dynamic loader would fail to find
  35 // the symbols when actually trying to launch the program on macOS 10.13. To
  36 // turn this into a compile-time issue instead, declarations are annotated with
  37 // when they were introduced, and the compiler can produce a diagnostic if the
  38 // program references something that isn't available on the deployment target.
  39 //
  40 // This mechanism is general in nature, and any vendor can add their markup to
  41 // the library (see below). Whenever a new feature is added that requires support
  42 // in the shared library, two macros are added below to allow marking the feature
  43 // as unavailable:
  44 // 1. A macro named `_LIBCPP_AVAILABILITY_HAS_NO_<feature>` which must be defined
  45 //    exactly when compiling for a target that doesn't support the feature.
  46 // 2. A macro named `_LIBCPP_AVAILABILITY_<feature>`, which must always be defined
  47 //    and must expand to the proper availability attribute for the platform.
  48 //
  49 // When vendors decide to ship the feature as part of their shared library, they
  50 // can update these macros appropriately for their platform, and the library will
  51 // use those to provide an optimal user experience.
  52 //
  53 // Furthermore, many features in the standard library have corresponding
  54 // feature-test macros. The `_LIBCPP_AVAILABILITY_HAS_NO_<feature>` macros
  55 // are checked by the corresponding feature-test macros generated by
  56 // generate_feature_test_macro_components.py to ensure that the library
  57 // doesn't announce a feature as being implemented if it is unavailable on
  58 // the deployment target.
  59 //
  60 // Note that this mechanism is disabled by default in the "upstream" libc++.
  61 // Availability annotations are only meaningful when shipping libc++ inside
  62 // a platform (i.e. as a system library), and so vendors that want them should
  63 // turn those annotations on at CMake configuration time.
  64 //
  65 // [1]: https://clang.llvm.org/docs/AttributeReference.html#availability
  66
  67 // For backwards compatibility, allow users to define _LIBCPP_DISABLE_AVAILABILITY
  68 // for a while.
  69 #if defined(_LIBCPP_DISABLE_AVAILABILITY)
  70 #  if !defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
  71 #    define _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
  72 #  endif
  73 #endif
  74
  75 // Availability markup is disabled when building the library, or when a non-Clang
  76 // compiler is used because only Clang supports the necessary attributes.
  77 // doesn't support the proper attributes.
  78 #if defined(_LIBCPP_BUILDING_LIBRARY) || defined(_LIBCXXABI_BUILDING_LIBRARY) || !defined(_LIBCPP_COMPILER_CLANG_BASED)
  79 #  if !defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
  80 #    define _LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS
  81 #  endif
  82 #endif
  83
  84 #if defined(_LIBCPP_HAS_NO_VENDOR_AVAILABILITY_ANNOTATIONS)
  85
  86 // These macros control the availability of std::bad_optional_access and
  87 // other exception types. These were put in the shared library to prevent
  88 // code bloat from every user program defining the vtable for these exception
  89 // types.
  90 //
  91 // Note that when exceptions are disabled, the methods that normally throw
  92 // these exceptions can be used even on older deployment targets, but those
  93 // methods will abort instead of throwing.
  94 #  define _LIBCPP_AVAILABILITY_HAS_BAD_OPTIONAL_ACCESS 1
  95 #  define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
  96
  97 #  define _LIBCPP_AVAILABILITY_HAS_BAD_VARIANT_ACCESS 1
  98 #  define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
  99
 100 #  define _LIBCPP_AVAILABILITY_HAS_BAD_ANY_CAST 1
 101 #  define _LIBCPP_AVAILABILITY_BAD_ANY_CAST
 102
 103 // These macros controls the availability of __cxa_init_primary_exception
 104 // in the built library, which std::make_exception_ptr might use
 105 // (see libcxx/include/__exception/exception_ptr.h).
 106 #  define _LIBCPP_AVAILABILITY_HAS_INIT_PRIMARY_EXCEPTION 1
 107 #  define _LIBCPP_AVAILABILITY_INIT_PRIMARY_EXCEPTION
 108
 109 // These macros control the availability of all parts of <filesystem> that
 110 // depend on something in the dylib.
 111 #  define _LIBCPP_AVAILABILITY_HAS_FILESYSTEM_LIBRARY 1
 112 #  define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY
 113 #  define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY_PUSH
 114 #  define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY_POP
 115
 116 // This controls the availability of floating-point std::to_chars functions.
 117 // These overloads were added later than the integer overloads.
 118 #  define _LIBCPP_AVAILABILITY_HAS_TO_CHARS_FLOATING_POINT 1
 119 #  define _LIBCPP_AVAILABILITY_TO_CHARS_FLOATING_POINT
 120
 121 // This controls the availability of the C++20 synchronization library,
 122 // which requires shared library support for various operations
 123 // (see libcxx/src/atomic.cpp). This includes <barier>, <latch>,
 124 // <semaphore>, and notification functions on std::atomic.
 125 #  define _LIBCPP_AVAILABILITY_HAS_SYNC 1
 126 #  define _LIBCPP_AVAILABILITY_SYNC
 127
 128 // This controls whether the library claims to provide a default verbose
 129 // termination function, and consequently whether the headers will try
 130 // to use it when the mechanism isn't overriden at compile-time.
 131 #  define _LIBCPP_AVAILABILITY_HAS_VERBOSE_ABORT 1
 132 #  define _LIBCPP_AVAILABILITY_VERBOSE_ABORT
 133
 134 // This controls the availability of the C++17 std::pmr library,
 135 // which is implemented in large part in the built library.
 136 #  define _LIBCPP_AVAILABILITY_HAS_PMR 1
 137 #  define _LIBCPP_AVAILABILITY_PMR
 138
 139 // This controls the availability of the C++20 time zone database.
 140 // The parser code is built in the library.
 141 #  define _LIBCPP_AVAILABILITY_HAS_TZDB 1
 142 #  define _LIBCPP_AVAILABILITY_TZDB
 143
 144 // This controls the availability of C++23 <print>, which
 145 // has a dependency on the built library (it needs access to
 146 // the underlying buffer types of std::cout, std::cerr, and std::clog.
 147 #  define _LIBCPP_AVAILABILITY_HAS_PRINT 1
 148 #  define _LIBCPP_AVAILABILITY_PRINT
 149
 150 // Enable additional explicit instantiations of iostreams components. This
 151 // reduces the number of weak definitions generated in programs that use
 152 // iostreams by providing a single strong definition in the shared library.
 153 //
 154 // TODO: Enable additional explicit instantiations on GCC once it supports exclude_from_explicit_instantiation,
 155 //       or once libc++ doesn't use the attribute anymore.
 156 // TODO: Enable them on Windows once https://llvm.org/PR41018 has been fixed.
 157 #  if !defined(_LIBCPP_COMPILER_GCC) && !defined(_WIN32)
 158 #    define _LIBCPP_AVAILABILITY_HAS_ADDITIONAL_IOSTREAM_EXPLICIT_INSTANTIATIONS_1 1
 159 #  else
 160 #    define _LIBCPP_AVAILABILITY_HAS_ADDITIONAL_IOSTREAM_EXPLICIT_INSTANTIATIONS_1 0
 161 #  endif
 162
 163 #elif defined(__APPLE__)
 164
 165 #  define _LIBCPP_AVAILABILITY_HAS_BAD_OPTIONAL_ACCESS                                                                 \
 166     (!defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) || __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ >= 50000)
 167
 168 #  define _LIBCPP_AVAILABILITY_HAS_BAD_VARIANT_ACCESS _LIBCPP_AVAILABILITY_HAS_BAD_OPTIONAL_ACCESS
 169 #  define _LIBCPP_AVAILABILITY_HAS_BAD_ANY_CAST _LIBCPP_AVAILABILITY_HAS_BAD_OPTIONAL_ACCESS
 170
 171 #  define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((availability(watchos, strict, introduced = 5.0)))
 172 #  define _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
 173 #  define _LIBCPP_AVAILABILITY_BAD_ANY_CAST _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
 174
 175 // TODO: Update once this is released
 176 #  define _LIBCPP_AVAILABILITY_HAS_INIT_PRIMARY_EXCEPTION 0
 177 #  define _LIBCPP_AVAILABILITY_INIT_PRIMARY_EXCEPTION __attribute__((unavailable))
 178
 179 // <filesystem>
 180 // clang-format off
 181 #  if (defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 101500) ||   \
 182       (defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ < 130000) || \
 183       (defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ < 130000) ||         \
 184       (defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ < 60000)
 185 // clang-format on
 186 #    define _LIBCPP_AVAILABILITY_HAS_FILESYSTEM_LIBRARY 0
 187 #  else
 188 #    define _LIBCPP_AVAILABILITY_HAS_FILESYSTEM_LIBRARY 1
 189 #  endif
 190 #  define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY                                                                      \
 191     __attribute__((availability(macos, strict, introduced = 10.15)))                                                   \
 192     __attribute__((availability(ios, strict, introduced = 13.0)))                                                      \
 193     __attribute__((availability(tvos, strict, introduced = 13.0)))                                                     \
 194     __attribute__((availability(watchos, strict, introduced = 6.0)))
 195 // clang-format off
 196 #   define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY_PUSH                                 \
 197         _Pragma("clang attribute push(__attribute__((availability(macos,strict,introduced=10.15))), apply_to=any(function,record))") \
 198         _Pragma("clang attribute push(__attribute__((availability(ios,strict,introduced=13.0))), apply_to=any(function,record))")    \
 199         _Pragma("clang attribute push(__attribute__((availability(tvos,strict,introduced=13.0))), apply_to=any(function,record))")   \
 200         _Pragma("clang attribute push(__attribute__((availability(watchos,strict,introduced=6.0))), apply_to=any(function,record))")
 201 #   define _LIBCPP_AVAILABILITY_FILESYSTEM_LIBRARY_POP                                  \
 202         _Pragma("clang attribute pop")                                          \
 203         _Pragma("clang attribute pop")                                          \
 204         _Pragma("clang attribute pop")                                          \
 205         _Pragma("clang attribute pop")
 206 // clang-format on
 207
 208 // std::to_chars(floating-point)
 209 // clang-format off
 210 #  if (defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 130300) ||   \
 211       (defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ < 160300) || \
 212       (defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ < 160300) ||         \
 213       (defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ < 90300)
 214 // clang-format on
 215 #    define _LIBCPP_AVAILABILITY_HAS_TO_CHARS_FLOATING_POINT 0
 216 #  else
 217 #    define _LIBCPP_AVAILABILITY_HAS_TO_CHARS_FLOATING_POINT 1
 218 #  endif
 219 #  define _LIBCPP_AVAILABILITY_TO_CHARS_FLOATING_POINT                                                                 \
 220     __attribute__((availability(macos, strict, introduced = 13.3)))                                                    \
 221     __attribute__((availability(ios, strict, introduced = 16.3)))                                                      \
 222     __attribute__((availability(tvos, strict, introduced = 16.3)))                                                     \
 223     __attribute__((availability(watchos, strict, introduced = 9.3)))
 224
 225 // c++20 synchronization library
 226 // clang-format off
 227 #   if (defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 110000) ||   \
 228        (defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ < 140000) || \
 229        (defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ < 140000) ||         \
 230        (defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ < 70000)
 231 // clang-format on
 232 #    define _LIBCPP_AVAILABILITY_HAS_SYNC 0
 233 #  else
 234 #    define _LIBCPP_AVAILABILITY_HAS_SYNC 1
 235 #  endif
 236 #  define _LIBCPP_AVAILABILITY_SYNC                                                                                    \
 237     __attribute__((availability(macos, strict, introduced = 11.0)))                                                    \
 238     __attribute__((availability(ios, strict, introduced = 14.0)))                                                      \
 239     __attribute__((availability(tvos, strict, introduced = 14.0)))                                                     \
 240     __attribute__((availability(watchos, strict, introduced = 7.0)))
 241
 242 // __libcpp_verbose_abort
 243 // TODO: Update once this is released
 244 #  define _LIBCPP_AVAILABILITY_HAS_VERBOSE_ABORT 0
 245
 246 #  define _LIBCPP_AVAILABILITY_VERBOSE_ABORT __attribute__((unavailable))
 247
 248 // std::pmr
 249 // clang-format off
 250 #  if (defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 140000) ||   \
 251       (defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ < 170000) || \
 252       (defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ < 170000) ||         \
 253       (defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ < 100000)
 254 // clang-format on
 255 #    define _LIBCPP_AVAILABILITY_HAS_PMR 0
 256 #  else
 257 #    define _LIBCPP_AVAILABILITY_HAS_PMR 1
 258 #  endif
 259 // TODO: Enable std::pmr markup once https://github.com/llvm/llvm-project/issues/40340 has been fixed
 260 //       Until then, it is possible for folks to try to use `std::pmr` when back-deploying to targets that don't support
 261 //       it and it'll be a load-time error, but we don't have a good alternative because the library won't compile if we
 262 //       use availability annotations until that bug has been fixed.
 263 #  if 0
 264 #    define _LIBCPP_AVAILABILITY_PMR                                                                                   \
 265       __attribute__((availability(macos, strict, introduced = 14.0)))                                                  \
 266       __attribute__((availability(ios, strict, introduced = 17.0)))                                                    \
 267       __attribute__((availability(tvos, strict, introduced = 17.0)))                                                   \
 268       __attribute__((availability(watchos, strict, introduced = 10.0)))
 269 #  else
 270 #    define _LIBCPP_AVAILABILITY_PMR
 271 #  endif
 272
 273 #  define _LIBCPP_AVAILABILITY_HAS_TZDB 0
 274 #  define _LIBCPP_AVAILABILITY_TZDB __attribute__((unavailable))
 275
 276 // Warning: This availability macro works differently than the other macros.
 277 // The dylib part of print is not needed on Apple platforms. Therefore when
 278 // the macro is not available the code calling the dylib is commented out.
 279 // The macro _LIBCPP_AVAILABILITY_PRINT is not used.
 280 #  define _LIBCPP_AVAILABILITY_HAS_PRINT 0
 281 #  define _LIBCPP_AVAILABILITY_PRINT __attribute__((unavailable))
 282
 283 // clang-format off
 284 #  if (defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 120000)   || \
 285       (defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ < 150000) || \
 286       (defined(__ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_TV_OS_VERSION_MIN_REQUIRED__ < 150000)         || \
 287       (defined(__ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__) && __ENVIRONMENT_WATCH_OS_VERSION_MIN_REQUIRED__ < 80000)
 288 // clang-format on
 289 #    define _LIBCPP_AVAILABILITY_HAS_ADDITIONAL_IOSTREAM_EXPLICIT_INSTANTIATIONS_1 0
 290 #  else
 291 #    define _LIBCPP_AVAILABILITY_HAS_ADDITIONAL_IOSTREAM_EXPLICIT_INSTANTIATIONS_1 1
 292 #  endif
 293 #else
 294
 295 // ...New vendors can add availability markup here...
 296
 297 #  error                                                                                                               \
 298       "It looks like you're trying to enable vendor availability markup, but you haven't defined the corresponding macros yet!"
 299
 300 #endif
 301
 302 // Define availability attributes that depend on _LIBCPP_HAS_NO_EXCEPTIONS.
 303 // Those are defined in terms of the availability attributes above, and
 304 // should not be vendor-specific.
 305 #if defined(_LIBCPP_HAS_NO_EXCEPTIONS)
 306 #  define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST
 307 #  define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS
 308 #  define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS
 309 #else
 310 #  define _LIBCPP_AVAILABILITY_THROW_BAD_ANY_CAST _LIBCPP_AVAILABILITY_BAD_ANY_CAST
 311 #  define _LIBCPP_AVAILABILITY_THROW_BAD_OPTIONAL_ACCESS _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
 312 #  define _LIBCPP_AVAILABILITY_THROW_BAD_VARIANT_ACCESS _LIBCPP_AVAILABILITY_BAD_VARIANT_ACCESS
 313 #endif
 314
 315 // Define availability attributes that depend on both
 316 // _LIBCPP_HAS_NO_EXCEPTIONS and _LIBCPP_HAS_NO_RTTI.
 317 #if defined(_LIBCPP_HAS_NO_EXCEPTIONS) || defined(_LIBCPP_HAS_NO_RTTI)
 318 #  undef _LIBCPP_AVAILABILITY_HAS_INIT_PRIMARY_EXCEPTION
 319 #  undef _LIBCPP_AVAILABILITY_INIT_PRIMARY_EXCEPTION
 320 #  define _LIBCPP_AVAILABILITY_HAS_INIT_PRIMARY_EXCEPTION 0
 321 #  define _LIBCPP_AVAILABILITY_INIT_PRIMARY_EXCEPTION
 322 #endif
 323
 324 #endif // _LIBCPP___AVAILABILITY