build/android/README.md

1 # android-cmake
9     cmake -DCMAKE_TOOLCHAIN_FILE=android.toolchain.cmake \
10           -DANDROID_NDK=<ndk_path>                       \
11           -DCMAKE_BUILD_TYPE=Release                     \
12           -DANDROID_ABI="armeabi-v7a with NEON"          \
14     cmake --build .
16 One-liner:
18 …-DCMAKE_TOOLCHAIN_FILE=android.toolchain.cmake -DANDROID_NDK=<ndk_path> -DCMAKE_BUILD_TYPE=Release…
20 _android-cmake_ will search for your NDK install in the following order:
27 So if you have installed the NDK as `~/android-ndk-r10d` then _android-cmake_ will locate it automa…
31 To build a cmake-based C/C++ project for Android you need:
36 The _android-cmake_ is also capable to build with NDK from AOSP or Linaro Android source tree, but …
40 Folowing the _ndk-build_ the _android-cmake_ supports **only two build targets**:
42 * `-DCMAKE_BUILD_TYPE=Release`
43 * `-DCMAKE_BUILD_TYPE=Debug`
47 ## Difference from _ndk-build_
50 * `Release` builds with `-O3` instead of `-Os`;
51 * `Release` builds without debug info (without `-g`) (because _ndk-build_ always creates a stripped…
52 * `-fsigned-char` is added to compiler flags to make `char` signed by default as it is on x86/x86_6…
57 The following features of _ndk-build_ are not supported by the _android-cmake_ yet:
59 * `armeabi-v7a-hard` ABI
64 …droid-cmake_ allows to select between several compiler toolchains and target platforms. Most of th…
66 * **ANDROID_NDK** - path to the Android NDK. If not set then _android-cmake_ will search for the mo…
67 …- specifies the target Application Binary Interface (ABI). This option nearly matches to the APP_A…
68     * `armeabi` - ARMv5TE based CPU with software floating point operations;
69     * **`armeabi-v7a`** - ARMv7 based devices with hardware FPU instructions (VFPv3_D16);
70     * `armeabi-v7a with NEON` - same as armeabi-v7a, but sets NEON as floating-point unit;
71     * `armeabi-v7a with VFPV3` - same as armeabi-v7a, but sets VFPv3_D32 as floating-point unit;
72     * `armeabi-v6 with VFP` - tuned for ARMv6 processors having VFP;
73     * `x86` - IA-32 instruction set
74     * `mips` - MIPS32 instruction set
75     * `arm64-v8a` - ARMv8 AArch64 instruction set - only for NDK r10 and newer
76     * `x86_64` - Intel64 instruction set (r1) - only for NDK r10 and newer
77     * `mips64` - MIPS64 instruction set (r6) - only for NDK r10 and newer
78 * **ANDROID_NATIVE_API_LEVEL** - level of android API to build for. Can be set either to full name …
79     * `android-8` for ARM;
80     * `android-9` for x86 and MIPS;
81     * `android-21` for 64-bit ABIs.
83     Building for `android-L` is possible only when it is explicitly selected.
84 …- the name of compiler toolchain to be used. This option allows to select between different GCC an…
87     * `aarch64-linux-android-4.9`
88     * `aarch64-linux-android-clang3.5`
89     * `arm-linux-androideabi-4.8`
90     * `arm-linux-androideabi-4.9`
91     * `arm-linux-androideabi-clang3.5`
92     * `mips64el-linux-android-4.9`
93     * `mipsel-linux-android-4.8`
94     * `x86-4.9`
95     * `x86_64-4.9`
97 * **ANDROID_STL** - the name of C++ runtime to use. The default is `gnustl_static`.
98     * `none` - do not configure the runtime.
99     * `system` - use the default minimal system C++ runtime library.
100         * Implies `-fno-rtti -fno-exceptions`.
101     * `system_re` - use the default minimal system C++ runtime library.
102         * Implies `-frtti -fexceptions`.
103     * `gabi++_static` - use the GAbi++ runtime as a static library.
104         * Implies `-frtti -fno-exceptions`.
106     * `gabi++_shared` - use the GAbi++ runtime as a shared library.
107         * Implies `-frtti -fno-exceptions`.
109     * `stlport_static` - use the STLport runtime as a static library.
110         * Implies `-fno-rtti -fno-exceptions` for NDK before r7.
111         * Implies `-frtti -fno-exceptions` for NDK r7 and newer.
112     * `stlport_shared` - use the STLport runtime as a shared library.
113         * Implies `-fno-rtti -fno-exceptions` for NDK before r7.
114         * Implies `-frtti -fno-exceptions` for NDK r7 and newer.
115     * **`gnustl_static`** - use the GNU STL as a static library.
116         * Implies `-frtti -fexceptions`.
117     * `gnustl_shared` - use the GNU STL as a shared library.
118         * Implies `-frtti -fno-exceptions`.
121 * **NDK_CCACHE** - path to `ccache` executable. If not set then initialized from `NDK_CCACHE` envir…
123 ## Advanced _android-cmake_ options
125 Normally _android-cmake_ users are not supposed to touch these variables but they might be useful t…
127 …BUILD** = `OFF` - generate 32-bit ARM instructions instead of Thumb. Applicable only for arm ABIs …
128 * **ANDROID_NO_UNDEFINED** = `ON` - show all undefined symbols as linker errors;
129 * **ANDROID_SO_UNDEFINED** = `OFF` - allow undefined symbols in shared libraries;
131 * **ANDROID_STL_FORCE_FEATURES** = `ON` - automatically configure rtti and exceptions support based…
132 * **ANDROID_NDK_LAYOUT** = `RELEASE` - inner layout of Android NDK, should be detected automaticall…
133     * `RELEASE` - public releases from Google;
134     * `LINARO` - NDK from Linaro project;
135     * `ANDROID` - NDK from AOSP.
136 …- enables saparate putting each function and data items into separate sections and enable garbage …
137 * **ANDROID_GOLD_LINKER** = `ON` - use gold linker with GCC 4.6 for NDK r8b and newer (only for ARM…
138 * **ANDROID_NOEXECSTACK** = `ON` - enables or disables stack execution protection code (`-Wl,-z,noe…
139 * **ANDROID_RELRO** = `ON` - Enables RELRO - a memory corruption mitigation technique (`-Wl,-z,relr…
140 * **ANDROID_LIBM_PATH** - path to `libm.so` (set to something like `$(TOP)/out/target/product/<prod…
142 ## Fine-tuning `CMakeLists.txt` for _android-cmake_
146 _android-cmake_ defines `ANDROID` CMake variable which can be used to add Android-specific stuff:
154 * `armv5te` - for `armeabi` ABI
155 * `armv6` - for `armeabi-v6 with VFP` ABI
156 * `armv7-a` - for `armeabi-v7a`, `armeabi-v7a with VFPV3` and `armeabi-v7a with NEON` ABIs
157 * `aarch64` - for `arm64-v8a` ABI
158 * `i686` - for `x86` ABI
159 * `x86_64` - for `x86_64` ABI
160 * `mips` - for `mips` ABI
161 * `mips64` - for `mips64` ABI
163 Other variables that are set by _android-cmake_ and can be used for the fine-grained build configur…
165 * `NEON` - set if target ABI supports Neon;
166 * `ANDROID_NATIVE_API_LEVEL` - native Android API level we are building for (note: Java part of And…
167 * `ANDROID_NDK_RELEASE` - version of the Android NDK
168 * `ANDROID_NDK_HOST_SYSTEM_NAME` - "windows", "linux-x86" or "darwin-x86" depending on the host pla…
169 * `ANDROID_RTTI` - set if rtti is enabled by the runtime
170 * `ANDROID_EXCEPTIONS` - set if exceptions are enabled by the runtime
174 …kages belonging to the same build target. So _android-cmake_ configures CMake to search in Android…
180 …a host package even when cross-compiling. For example you can be searching for your documentation …
185 …g package search into platform-specific logic you can copy the following snippet into your project…
207 …ical flags, so don't loose them. Also be aware that _android-cmake_ also sets configuration-specif…
213 First of all `cygwin` builds are **NOT supported** and will not be supported by _android-cmake_. To…
220 * Pass `-GNinja` to `cmake` alongside with other arguments (or choose Ninja generator in `cmake-gui…
227     * `mingw-make` should work as fine;
230 * Pass `-G"MinGW Makefiles"` and `-DCMAKE_MAKE_PROGRAM="<full/path/to/>make.exe"`
232 * Run `make.exe` or `cmake --build .` for single-threaded build.
236 The _android-cmake_ should correctly handle projects with assembler sources (`*.s` or `*.S`). But i…
240 _android-cmake_ is distributed under the terms of [BSD 3-Clause License](http://opensource.org/lice…