From d8f46916b6d1b26bc351a631ca5a6fe099e4b029 Mon Sep 17 00:00:00 2001 From: Dan Albert Date: Fri, 7 Aug 2020 13:54:49 -0700 Subject: [PATCH] Add api-level.h to dac, improve docs. We don't list most of bionic on dac since it would be overwhelming for the current layout, but this file in particular seems useful, especially __ANDROID_API__. Unfortunately, c2devsite doesn't include macro documentation. Until then, it's still useful to include the functions defined in this header. I've also elaborated a bit in the __ANDROID_API__ documentation, since the existing phrasing led to confusion over whether it was closer to minSdkVersion or compileSdkVersion. In practice these are identical for the NDK, but if we switch to weakly-linked APIs via the availability attribute that would change. Test: built docs, looked at them Bug: None Change-Id: I5cf78a6143b5c15790c369bdf888611e4c1189db --- libc/include/android/api-level.h | 52 ++++++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 6 deletions(-) diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h index 50cb61a6b..bcddddd59 100644 --- a/libc/include/android/api-level.h +++ b/libc/include/android/api-level.h @@ -28,6 +28,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 + * ``. + * + * 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__ @@ -114,9 +152,9 @@ __BEGIN_DECLS #define __ANDROID_API_S__ 31 /** - * 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 ``, * and is equivalent to the AndroidManifest.xml `targetSdkVersion`. @@ -148,3 +186,5 @@ int android_get_device_api_level() __INTRODUCED_IN(29); #endif __END_DECLS + +/** @} */