README.md
1Android Native Development Kit (NDK)
2====================================
3
4The NDK allows Android application developers to include
5native code in their Android application packages, compiled as JNI shared
6libraries.
7
8Discussions related to the Android NDK happen on the
9[android-ndk](http://groups.google.com/group/android-ndk) Google Group.
10
11Building the NDK
12================
13
14**Note:** This document is for developers _of_ the NDK, not developers
15that use the NDK.
16
17Both Linux and Windows host binaries are built on Linux machines. Windows host
18binaries are built via MinGW cross compiler. Systems without a working MinGW
19compiler can use `build/tools/build-mingw64-toolchain.sh` to generate their own
20and be added to the `PATH` for build scripts to discover.
21
22Building binaries for Mac OS X requires at least 10.8.
23
24Target headers and binaries are built on Linux.
25
26Components
27----------
28
29The 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
61Prerequisites
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
88Host/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
104builds, namely `--arch` and `--module`.
105
106Packaging
107---------
108
109The simplest way to package an NDK on Linux is to just omit the `--no-package`
110flag when running `checkbuild.py`. This will take a little longer though, so it
111may not be desired for day to day development.
112
113If you need to re-run just the packaging step without going through a build,
114packaging is handled by `build/tools/package.py`.
115
116Testing
117-------
118
119Running the NDK tests requires a complete NDK package (see previous steps).
120From 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
126To run the tests with Clang, use the option `--toolchain clang`.
127
128The full test suite includes tests which run on a device or emulator, so you'll
129need to have adb in your path and `ANDROID_SERIAL` set if more than one
130device/emulator is connected. If you do not have a device capable of running the
131tests, you can run just the `build` or `awk` test suites with the `--suite`
132flag.
133
134The libc++ tests are not currently integrated into the main NDK tests. To run
135the libc++ tests:
136
137```bash
138$ NDK=/path/to/extracted/ndk sources/cxx-stl/llvm-libc++/llvm/ndk-test.sh $ABI
139```
140
141Note that these tests are far from failure free (especially on 32-bit ARM). In
142general, most of these tests are locale related and fail because we don't
143support anything beyond the C locale. The ARM32 specific failures are because
144the libgcc unwinder does not get along with the LLVM unwinder. The test config
145file (`$NDK/sources/cxx-stl/llvm-libc++/libcxx/test/libcxx/ndk/test/config.py`)
146can be modified to use `-lc++_static` *before* `-lgcc` and the tests will then
147work on ARM (but will take considerably longer to run).
148
149Yes, 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
151regression from r10e.
152