Remove __ANDROID_NDK__ from bionic, and document our #defines.
__ANDROID_NDK__ is moving into the NDK's <android/ndk-version.h>
instead.
Test: treehugger
Change-Id: I192016165a929547009d15dbcc30e8f6dad1ac88
diff --git a/docs/defines.md b/docs/defines.md
new file mode 100644
index 0000000..4775cd2
--- /dev/null
+++ b/docs/defines.md
@@ -0,0 +1,66 @@
+# When to use which `#define`
+
+Using `#ifdef` or equivalents is common when writing portable code. Which to use
+when can be quite tricky. This document describes the most common choices
+related to Android.
+
+## `__BIONIC__`
+
+If your code is specific to Android's C library, bionic, use `__BIONIC__`. This
+is typically a good choice when you use libc API that's only in bionic, such as
+the system property functions. Common alternatives on this dimension are
+`__GLIBC__`, `__APPLE__`, or `_WIN32`. Note that although bionic is most often
+seen on Android devices, it is possible to use bionic on the host too.
+
+## `__ANDROID__`
+
+If your code is specific to Android devices, use `__ANDROID__`. This isn't
+useful as you might think, and one of the other choices on this page is usually
+more appropriate. This is typically a good choice if you have code that's part
+of the OS and needs to behave differently on the host than on the device.
+Genuine cases are quite rare, and `__BIONIC__` is often more specific (but
+remember that it is possible -- if unusual -- to use bionic on the host).
+
+## `__ANDROID_API__`
+
+If your code can be built targeting a variety of different OS versions, use
+`__ANDROID_API__` to test which version you're building against. This is
+typically useful if you can use new NDK APIs when available, but don't require
+them if not.
+
+One thing to note (if your code may also be built as part of the OS itself) is
+that for most of the year, the OS builds with this set to 10,000 rather than the
+obvious "next" API level such as 19. Once the API level has been decided, the
+value of `__ANDROID_API__` drops to that number.
+
+## `__linux__`
+
+If your code requires a Linux kernel, use `__linux__`. This is typically a good
+choice when you use Linux-specific API, such as a Linux-specific system call or
+a file in `/proc`, but aren't restricted to just Android and would work equally
+well on a desktop Linux distro, say. Common alternatives on this dimension
+are `__APPLE__` or `_WIN32`.
+
+## `__ANDROID_NDK__`
+
+If your code can be built either as part of an app _or_ as part of the OS
+itself, use `__ANDROID_NDK__` to differentiate between those two circumstances.
+This is typically a good choice when your code uses non-NDK API if it's built as
+part of the OS, but sticks to just the NDK APIs otherwise.
+
+## `__NDK_MAJOR__`, `__NDK_MINOR__`, `__NDK_BETA__`, `__NDK_BUILD__`, `__NDK_CANARY__`
+
+If your code can be built with a variety of different NDK versions, and needs to
+work around issues with some of them, use these macros to detect the versinon of
+the NDK you're being built with. Usually only `__NDK_MAJOR__` will be necessary.
+
+## `__arm__`, `__aarch64__`, `__i386__`, `__x86_64__`
+
+If your code is specific to a particular processor architecture, use these
+macros to conditionally compile. Note that the ABI usually called `arm64` uses
+the macro `__aarch64__` and the ABI usually called `x86` uses `__i386__`.
+
+## `__LP32__` and `__LP64__`
+
+If your code depends on "bitness" -- whether `long` and pointers are 32- or
+64-bit -- use these macros to conditionally compile.
diff --git a/libc/include/android/api-level.h b/libc/include/android/api-level.h
index 4a3d052..577fb00 100644
--- a/libc/include/android/api-level.h
+++ b/libc/include/android/api-level.h
@@ -31,6 +31,9 @@
/**
* @file android/api-level.h
* @brief Functions and constants for dealing with multiple API levels.
+ *
+ * See
+ * https://android.googlesource.com/platform/bionic/+/master/docs/defines.md.
*/
#include <sys/cdefs.h>
@@ -38,9 +41,9 @@
__BEGIN_DECLS
/**
- * Magic version number for an Android OS build which has
- * not yet turned into an official release,
- * for comparison against `__ANDROID_API__`.
+ * Magic version number for an Android OS build which has not yet turned
+ * into an official release, for comparison against `__ANDROID_API__`. See
+ * https://android.googlesource.com/platform/bionic/+/master/docs/defines.md.
*/
#define __ANDROID_API_FUTURE__ 10000
@@ -49,27 +52,12 @@
/**
* `__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.
+ * compiler system based on the API level you claimed to target. See
+ * https://android.googlesource.com/platform/bionic/+/master/docs/defines.md.
*/
#define __ANDROID_API__ __ANDROID_API_FUTURE__
#endif
-#if __ANDROID_API__ != __ANDROID_API_FUTURE__
-/**
- * `__ANDROID_NDK__` is defined for code that's built by the NDK
- * rather than as part of the OS. "Built by the NDK" is an ambiguous idea,
- * so you might prefer to check `__ANDROID__`, `__BIONIC__`, `__linux__`,
- * or `__NDK_MAJOR__` instead, depending on exactly what you're trying to say.
- *
- * `__ANDROID_NDK__` is intended to capture "this code is being built for
- * Android, but targeting a specific API level". This is true for all code built
- * by the NDK proper, but also for OS code that sets `sdk_version` in its build
- * file. This distinction might matter to you if, for example, your code could
- * be built as part of an app *or* as part of the OS.
- */
-#define __ANDROID_NDK__ 1
-#endif
-
/** Names the Gingerbread API level (9), for comparison against `__ANDROID_API__`. */
#define __ANDROID_API_G__ 9
diff --git a/libc/include/sys/cdefs.h b/libc/include/sys/cdefs.h
index b061c22..8078bda 100644
--- a/libc/include/sys/cdefs.h
+++ b/libc/include/sys/cdefs.h
@@ -36,6 +36,10 @@
#pragma once
+/**
+ * `__BIONIC__` is always defined if you're building with bionic. See
+ * https://android.googlesource.com/platform/bionic/+/master/docs/defines.md.
+ */
#define __BIONIC__ 1
#if defined(__cplusplus)