Unified Headers

Issue #120

Currently, we have a set of libc headers for each API version. In many cases these headers are incorrect. Many expose APIs that didn‘t exist, and others don’t expose APIs that did.

Over the last few months we've done unified these into a single set of headers. This single header path will be used for every platform level. API level guards are handled with #ifdef. These headers can be found in prebuilts/ndk/headers.

Unified headers are built directly from the Android platform, so they will no longer be out of date or incorrect (or at the very least, any bugs in the NDK headers will also be a bug in the platform headers, which means we're much more likely to find them).

Known Issues

  • Standalone toolchains using GCC are not supported out of the box. To use GCC, pass -D__ANDROID_API__=$API when compiling.

Using Unified Headers

Enabling unified headers will depend on your build system.

ndk-build

Add the following to your Android.mk:

APP_UNIFIED_HEADERS := true

CMake

cmake -DANDROID_UNIFIED_HEADERS=ON ...

Standalone Toolchains

$NDK/build/tools/make_standalone_toolchain.py --unified-headers ...

Gradle

TBD

Supporting Unified Headers in Your Build System

App developers can stop reading here. The following information is only relevant to build system engineers.

Unified headers require only a few changes compared to using the legacy NDK headers. For reference, this patch added support to ndk-build: https://android-review.googlesource.com/c/239934/

  1. The compile time sysroot is now $NDK/sysroot. Previously this was $NDK/platforms/android-$API/arch-$ARCH.

  2. Pass -isystem $NDK/sysroot/usr/include/$TRIPLE when compiling. The triple has the following mapping:

    ArchTriple
    ARMarm-linux-androideabi
    ARM64aarch64-linux-android
    MIPSmipsel-linux-android
    MIPS64mips64el-linux-android
    x86i386-linux-android
    x86_64x86_64-linux-android

    This is needed for architecture specific headers such as those in asm/ and machine/. We plan to teach Clang's driver to automatically search the architecture specific include directory, but that has yet to be done.

  3. Pass -D__ANDROID_API__=$API when compiling. This define used to be provided by <android/api-level.h>, but with only one set of headers this is no longer possible. In the future we will look in to adding -mandroid-version or similar to Clang so this is automatic.

  4. At link time, change nothing. All link time build behavior should match the legacy headers behavior. --sysroot should still point to $NDK/platforms/android-$API/arch-$ARCH/.

OSZAR »