1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 /** 20 * @def __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ 21 * 22 * Controls whether calling APIs newer than the developer's minSdkVersion are a 23 * build error (when not defined) or allowed as a weak reference with a 24 * __builtin_available() guard (when defined). 25 * 26 * See https://developer.android.com/ndk/guides/using-newer-apis for more 27 * details. 28 */ 29 #if defined(__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__) 30 // In this mode, Clang will emit weak references to the APIs if the 31 // minSdkVersion is less than the __what argument. This allows the libraries to 32 // load even on systems too old to contain the API, but calls must be guarded 33 // with `__builtin_available(android api_level, *)` to avoid segfaults. 34 #define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,__what __VA_OPT__(,) __VA_ARGS__))) 35 36 // When the caller is using weak API references, we should expose the decls for 37 // APIs which are not available in the caller's minSdkVersion, otherwise there's 38 // no way to take advantage of the weak references. 39 #define __BIONIC_AVAILABILITY_GUARD(api_level) 1 40 #else 41 // The 'strict' flag is required for NDK clients where the code was not written 42 // to handle the case where the API was available at build-time but not at 43 // run-time. Most 3p code ported to Android was not written to use 44 // `__builtin_available()` for run-time availability checking, and so would not 45 // compile in this mode (or worse, if the build doesn't use 46 // -Werror=unguarded-availability, it would build but crash at runtime). 47 #define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,strict,__what __VA_OPT__(,) __VA_ARGS__))) 48 49 // When the caller is using strict API references, we hide APIs which are not 50 // available in the caller's minSdkVersion. This is a bionic-only deviation in 51 // behavior from the rest of the NDK headers, but it's necessary to maintain 52 // source compatibility with 3p libraries that either can't correctly detect API 53 // availability (either incorrectly detecting as always-available or as 54 // never-available, but neither is true), or define their own polyfills which 55 // conflict with our declarations. 56 // 57 // https://github.com/android/ndk/issues/2081 58 #define __BIONIC_AVAILABILITY_GUARD(api_level) (__ANDROID_MIN_SDK_VERSION__ >= (api_level)) 59 #endif 60 61 #pragma clang diagnostic push 62 #pragma clang diagnostic ignored "-Wc23-extensions" 63 // Passing no argument for the '...' parameter of a variadic macro is a C23 extension 64 #define __INTRODUCED_IN(api_level) __BIONIC_AVAILABILITY(introduced=api_level) 65 #pragma clang diagnostic pop 66 67 #define __DEPRECATED_IN(api_level, msg) __BIONIC_AVAILABILITY(deprecated=api_level, message=msg) 68 #define __REMOVED_IN(api_level, msg) __BIONIC_AVAILABILITY(obsoleted=api_level, message=msg) 69 70 // The same availability attribute can't be annotated multiple times. Therefore, the macros are 71 // defined for the configuration that it is valid for so that declarations like the below doesn't 72 // cause inconsistent availability values which is an error with -Wavailability: 73 // 74 // void foo() __INTRODUCED_IN_32(30) __INTRODUCED_IN_64(31); 75 // 76 #if !defined(__LP64__) 77 #define __INTRODUCED_IN_32(api_level) __BIONIC_AVAILABILITY(introduced=api_level) 78 #define __INTRODUCED_IN_64(api_level) 79 #else 80 #define __INTRODUCED_IN_32(api_level) 81 #define __INTRODUCED_IN_64(api_level) __BIONIC_AVAILABILITY(introduced=api_level) 82 #endif 83