diff options
Diffstat (limited to 'libc/include/android/api-level.h')
| -rw-r--r-- | libc/include/android/api-level.h | 62 |
1 files changed, 55 insertions, 7 deletions
diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h index 1b8af78cd..40846fb8b 100644 --- a/libc/include/android/api-level.h +++ b/libc/include/android/api-level.h @@ -29,6 +29,13 @@ #pragma once /** + * @defgroup apilevels API Levels + * + * Defines functions and constants for working with Android API levels. + * @{ + */ + +/** * @file android/api-level.h * @brief Functions and constants for dealing with multiple API levels. * @@ -50,9 +57,40 @@ __BEGIN_DECLS /* This #ifndef should never be true except when doxygen is generating docs. */ #ifndef __ANDROID_API__ /** - * `__ANDROID_API__` is the API level being targeted. For the OS, - * this is `__ANDROID_API_FUTURE__`. For the NDK, this is set by the - * compiler system based on the API level you claimed to target. See + * `__ANDROID_API__` is the [API + * level](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) + * this code is being built for. The resulting binaries are only guaranteed to + * be compatible with devices which have an API level greater than or equal to + * `__ANDROID_API__`. + * + * For NDK and APEX builds, this macro will always be defined. It is set + * automatically by Clang using the version suffix that is a part of the target + * name. For example, `__ANDROID_API__` will be 24 when Clang is given the + * argument `-target aarch64-linux-android24`. + * + * For non-APEX OS code, this defaults to __ANDROID_API_FUTURE__. + * + * The value of `__ANDROID_API__` can be compared to the named constants in + * `<android/api-level.h>`. + * + * The interpretation of `__ANDROID_API__` is similar to the AndroidManifest.xml + * `minSdkVersion`. In most cases `__ANDROID_API__` will be identical to + * `minSdkVersion`, but as it is a build time constant it is possible for + * library code to use a different value than the app it will be included in. + * When libraries and applications build for different API levels, the + * `minSdkVersion` of the application must be at least as high as the highest + * API level used by any of its libraries which are loaded unconditionally. + * + * Note that in some cases the resulting binaries may load successfully on + * devices with an older API level. That behavior should not be relied upon, + * even if you are careful to avoid using new APIs, as the toolchain may make + * use of new features by default. For example, additional FORTIFY features may + * implicitly make use of new APIs, SysV hashes may be omitted in favor of GNU + * hashes to improve library load times, or relocation packing may be enabled to + * reduce binary size. + * + * See android_get_device_api_level(), + * android_get_application_target_sdk_version() and * https://android.googlesource.com/platform/bionic/+/master/docs/defines.md. */ #define __ANDROID_API__ __ANDROID_API_FUTURE__ @@ -110,10 +148,16 @@ __BEGIN_DECLS /** Names the "R" API level (30), for comparison against `__ANDROID_API__`. */ #define __ANDROID_API_R__ 30 +/** Names the "S" API level (31), for comparison against `__ANDROID_API__`. */ +#define __ANDROID_API_S__ 31 + +/* This file is included in <features.h>, and might be used from .S files. */ +#if !defined(__ASSEMBLY__) + /** - * Returns the `targetSdkVersion` of the caller, or `__ANDROID_API_FUTURE__` - * if there is no known target SDK version (for code not running in the - * context of an app). + * Returns the `targetSdkVersion` of the caller, or `__ANDROID_API_FUTURE__` if + * there is no known target SDK version (for code not running in the context of + * an app). * * The returned values correspond to the named constants in `<android/api-level.h>`, * and is equivalent to the AndroidManifest.xml `targetSdkVersion`. @@ -126,7 +170,7 @@ int android_get_application_target_sdk_version() __INTRODUCED_IN(24); #if __ANDROID_API__ < 29 -// android_get_device_api_level is a static inline before API level 29. +/* android_get_device_api_level is a static inline before API level 29. */ #define __BIONIC_GET_DEVICE_API_LEVEL_INLINE static __inline #include <bits/get_device_api_level_inlines.h> #undef __BIONIC_GET_DEVICE_API_LEVEL_INLINE @@ -144,4 +188,8 @@ int android_get_device_api_level() __INTRODUCED_IN(29); #endif +#endif /* defined(__ASSEMBLY__) */ + __END_DECLS + +/** @} */ |