1 Android Native Development Kit (NDK) 2 ==================================== 3 4 The NDK allows Android application developers to include 5 native code in their Android application packages, compiled as JNI shared 6 libraries. 7 8 Discussions related to the Android NDK happen on the 9 [android-ndk](http://groups.google.com/group/android-ndk) Google Group. 10 11 Building the NDK 12 ================ 13 14 **Note:** This document is for developers _of_ the NDK, not developers 15 that use the NDK. 16 17 Both Linux and Windows host binaries are built on Linux machines. Windows host 18 binaries are built via MinGW cross compiler. Systems without a working MinGW 19 compiler can use `build/tools/build-mingw64-toolchain.sh` to generate their own 20 and be added to the `PATH` for build scripts to discover. 21 22 Building binaries for Mac OS X requires at least 10.8. 23 24 Target headers and binaries are built on Linux. 25 26 Components 27 ---------- 28 29 The NDK consists of three parts: host binaries, target prebuilts, and others 30 (build system, docs, samples, tests). 31 32 ### Host Binaries 33 34 * `toolchains/` contains GCC and Clang toolchains. 35 * `$TOOLCHAIN/config.mk` contains ARCH and ABIS this toolchain can handle. 36 * `$TOOLCHAIN/setup.mk` contains toolchain-specific default CFLAGS/LDFLAGS 37 when this toolchain is used. 38 * `binutils/` contains the standalone binutils installation for use with Clang. 39 * `host-tools/` contains build dependencies and additional tools. 40 * make, awk, python, yasm, and for Windows: cmp.exe and echo.exe 41 * `ndk-depends`, `ndk-stack` and `ndk-gdb` can also be found here. 42 43 ### Target Headers and Binaries 44 45 * `platforms/android-N/arch-$ARCH_NAME/` contains headers and libraries for each 46 API level. 47 * The build system sets `--sysroot` to one of these directories based on 48 user-specified `APP_ABI` and `APP_PLATFORM`. 49 * `sources/cxx-stl/$STL` contains the headers and libraries for the various C++ 50 STLs. 51 * `gdbserver/` contains gdbserver. 52 53 ### Others 54 55 * `build/` contains the ndk-build system and scripts to rebuild NDK. 56 * `docs/` 57 * `sources/` contains modules useful in samples and apps via 58 `$(call import-module, $MODULE)` 59 * `tests/` 60 61 Prerequisites 62 ------------- 63 64 * [AOSP NDK Repository](http://source.android.com/source/downloading.html) 65 * Check out the branch `master-ndk` 66 67 ```bash 68 repo init -u https://android.googlesource.com/platform/manifest \ 69 -b master-ndk 70 71 # Googlers, use 72 repo init -u \ 73 persistent-https://android.git.corp.google.com/platform/manifest \ 74 -b master-ndk 75 ``` 76 77 * Additional Linux Dependencies (available from apt): 78 * texinfo 79 * gcc-mingw32 80 * wine 81 * bison 82 * flex 83 * dmake 84 * libtool 85 * pbzip2 86 * Mac OS X also requires Xcode. 87 88 Host/Target prebuilts 89 --------------------- 90 91 ### For Linux or Darwin: 92 93 ```bash 94 $ python checkbuild.py --no-package 95 ``` 96 97 ### For Windows, from Linux: 98 99 ```bash 100 $ python checkbuild.py --system windows 101 ``` 102 103 `checkbuild.py` also accepts a variety of other options to speed up local 104 builds, namely `--arch` and `--module`. 105 106 Packaging 107 --------- 108 109 The simplest way to package an NDK on Linux is to just omit the `--no-package` 110 flag when running `checkbuild.py`. This will take a little longer though, so it 111 may not be desired for day to day development. 112 113 If you need to re-run just the packaging step without going through a build, 114 packaging is handled by `build/tools/package.py`. 115 116 Testing 117 ------- 118 119 Running the NDK tests requires a complete NDK package (see previous steps). 120 From the NDK source directory (not the extracted package): 121 122 ```bash 123 $ NDK=/path/to/extracted/ndk python tests/run-all.py --abi $ABI_TO_TEST 124 ``` 125 126 To run the tests with Clang, use the option `--toolchain clang`. 127 128 The full test suite includes tests which run on a device or emulator, so you'll 129 need to have adb in your path and `ANDROID_SERIAL` set if more than one 130 device/emulator is connected. If you do not have a device capable of running the 131 tests, you can run just the `build` or `awk` test suites with the `--suite` 132 flag. 133 134 The libc++ tests are not currently integrated into the main NDK tests. To run 135 the libc++ tests: 136 137 ```bash 138 $ NDK=/path/to/extracted/ndk sources/cxx-stl/llvm-libc++/llvm/ndk-test.sh $ABI 139 ``` 140 141 Note that these tests are far from failure free (especially on 32-bit ARM). In 142 general, most of these tests are locale related and fail because we don't 143 support anything beyond the C locale. The ARM32 specific failures are because 144 the libgcc unwinder does not get along with the LLVM unwinder. The test config 145 file (`$NDK/sources/cxx-stl/llvm-libc++/libcxx/test/libcxx/ndk/test/config.py`) 146 can be modified to use `-lc++_static` *before* `-lgcc` and the tests will then 147 work on ARM (but will take considerably longer to run). 148 149 Yes, this does mean that exception handling will often fail when using 150 `c++_shared` on ARM32. We should fix this ASAP, but this actually is not a 151 regression from r10e. 152