| Dan Albert | ab5740b | 2016-11-03 16:02:16 -0700 | [diff] [blame] | 1 | Unified Headers |
| 2 | =============== |
| 3 | |
| 4 | [Issue #120](https://github.com/android-ndk/ndk/issues/120) |
| 5 | |
| 6 | Currently, we have a set of libc headers for each API version. In many cases |
| 7 | these headers are incorrect. Many expose APIs that didn't exist, and others |
| 8 | don't expose APIs that did. |
| 9 | |
| 10 | Over the last few months we've done unified these into a single set of headers. |
| 11 | This single header path will be used for *every* platform level. API level |
| 12 | guards are handled with `#ifdef`. These headers can be found in |
| 13 | [prebuilts/ndk/headers]. |
| 14 | |
| 15 | Unified headers are built directly from the Android platform, so they will no |
| 16 | longer be out of date or incorrect (or at the very least, any bugs in the NDK |
| 17 | headers will also be a bug in the platform headers, which means we're much more |
| 18 | likely to find them). |
| 19 | |
| 20 | [prebuilts/ndk/headers]: https://android.googlesource.com/platform/prebuilts/ndk/+/master/headers/ |
| 21 | |
| 22 | |
| 23 | Known Issues |
| 24 | ------------ |
| 25 | |
| Dan Albert | ab5740b | 2016-11-03 16:02:16 -0700 | [diff] [blame] | 26 | * Standalone toolchains using GCC are not supported out of the box. To use GCC, |
| 27 | pass `-D__ANDROID_API__=$API` when compiling. |
| 28 | |
| Dan Albert | ab5740b | 2016-11-03 16:02:16 -0700 | [diff] [blame] | 29 | |
| 30 | Using Unified Headers |
| 31 | --------------------- |
| 32 | |
| 33 | Enabling unified headers will depend on your build system. |
| 34 | |
| 35 | ### ndk-build |
| 36 | |
| 37 | Add the following to your Android.mk: |
| 38 | |
| 39 | ```makefile |
| 40 | APP_UNIFIED_HEADERS := true |
| 41 | ``` |
| 42 | |
| 43 | ### CMake |
| 44 | |
| Dan Albert | ab5740b | 2016-11-03 16:02:16 -0700 | [diff] [blame] | 45 | ```bash |
| 46 | cmake -DANDROID_UNIFIED_HEADERS=ON ... |
| 47 | ``` |
| 48 | |
| 49 | ### Standalone Toolchains |
| 50 | |
| 51 | ```bash |
| 52 | $NDK/build/tools/make_standalone_toolchain.py --unified-headers ... |
| 53 | ``` |
| 54 | |
| 55 | ### Gradle |
| 56 | |
| 57 | TBD |
| 58 | |
| 59 | |
| 60 | Supporting Unified Headers in Your Build System |
| 61 | ----------------------------------------------- |
| 62 | |
| 63 | App developers can stop reading here. The following information is only |
| 64 | relevant to build system engineers. |
| 65 | |
| 66 | Unified headers require only a few changes compared to using the legacy NDK |
| 67 | headers. For reference, this patch added support to ndk-build: |
| 68 | https://android-review.googlesource.com/c/239934/ |
| 69 | |
| 70 | 1. The compile time sysroot is now `$NDK/sysroot`. Previously this was |
| 71 | `$NDK/platforms/android-$API/arch-$ARCH`. |
| 72 | |
| 73 | 2. Pass `-isystem $NDK/sysroot/usr/include/$TRIPLE` when compiling. The triple |
| 74 | has the following mapping: |
| 75 | |
| 76 | Arch | Triple |
| 77 | --------|------------------------- |
| 78 | ARM | `arm-linux-androideabi` |
| 79 | ARM64 | `aarch64-linux-android` |
| 80 | MIPS | `mipsel-linux-android` |
| 81 | MIPS64 | `mips64el-linux-android` |
| 82 | x86 | `i386-linux-android` |
| 83 | x86\_64 | `x86_64-linux-android` |
| 84 | |
| 85 | This is needed for architecture specific headers such as those in `asm/` and |
| 86 | `machine/`. We plan to teach Clang's driver to automatically search the |
| 87 | architecture specific include directory, but that has yet to be done. |
| 88 | |
| 89 | 3. Pass `-D__ANDROID_API__=$API` when compiling. This define used to be provided |
| 90 | by `<android/api-level.h>`, but with only one set of headers this is no |
| 91 | longer possible. In the future we will look in to adding `-mandroid-version` |
| 92 | or similar to Clang so this is automatic. |
| 93 | |
| 94 | 4. At link time, change nothing. All link time build behavior should match the |
| 95 | legacy headers behavior. `--sysroot` should still point to |
| 96 | `$NDK/platforms/android-$API/arch-$ARCH/`. |
