1'ndk-build' Overview 2=== 3 4I. Usage: 5--------- 6 7The Android NDK r4 introduced a new tiny shell script, named 'ndk-build', 8to simplify building machine code. 9 10The script is located at the top-level directory of the NDK, and shall 11be invoked from the command-line when in your application project 12directory, or any of its sub-directories. For example: 13 14 cd $PROJECT 15 $NDK/ndk-build 16 17Where $NDK points to your NDK installation path. You can also create an 18alias or add $NDK to your PATH to avoid typing it every time. 19 20 21II. Options: 22------------ 23 24All parameters to 'ndk-build' are passed directly to the underlying GNU Make 25command that runs the NDK build scripts. Notable uses include: 26 27 ndk-build --> rebuild required machine code. 28 ndk-build clean --> clean all generated binaries. 29 30 ndk-build NDK_DEBUG=1 --> generate debuggable native code. 31 32 ndk-build V=1 --> launch build, displaying build commands. 33 34 ndk-build -B --> force a complete rebuild. 35 36 ndk-build -B V=1 --> force a complete rebuild and display build 37 commands. 38 39 ndk-build NDK_LOG=1 --> display internal NDK log messages 40 (used for debugging the NDK itself). 41 42 ndk-build NDK_DEBUG=1 --> force a debuggable build (see below) 43 ndk-build NDK_DEBUG=0 --> force a release build (see below) 44 45 ndk-build NDK_HOST_32BIT=1 --> Always use toolchain in 32-bit (see below) 46 47 ndk-build NDK_APPLICATION_MK=<file> 48 --> rebuild, using a specific Application.mk pointed to by 49 the NDK_APPLICATION_MK command-line variable. 50 51 ndk-build -C <project> --> build the native code for the project 52 path located at <project>. Useful if you 53 don't want to 'cd' to it in your terminal. 54 55 56III. Debuggable versus Release builds: 57-------------------------------------- 58 59In NDK r5, ndk-build has been modified to make it easier to switch between 60release and debug builds. This is done by using the NDK_DEBUG variable. 61For example: 62 63 $NDK/ndk-build NDK_DEBUG=1 => forces the generation of debug binaries 64 $NDK/ndk-build NDK_DEBUG=0 => forces the generation of release binaries 65 66If you don't specify NDK_DEBUG, ndk-build will keep its default behaviour, 67which is to inspect the AndroidManifest.xml, if any, and see if its 68<application> element has android:debuggable="true". 69 70> IMPORTANT: 71If you use the build tools of SDK r8 (or higher), you 72won't need to touch your AndroidManifest.xml file at all! 73 74> That's because if you build a debug package (e.g. with 75"ant debug" or the corresponding option of the ADT plugin), 76the tool will automatically pick the native debug files 77generated with NDK_DEBUG=1. 78 79Also, as a convenience, the release and debug object files generated by the 80NDK are now stored in different directories (e.g. obj/local/<abi>/objs and 81obj/local/<abi>/objs-debug). This avoids having to recompile all your sources 82when you switch between these two modes (even when you only modified one or 83two source files). 84 85 86IV. 64-bit and 32-bit toolchains: 87--------------------------------- 88 89Some toolchains come with both 64-bit and 32-bit versions. For example, 90directories `$NDK/toolchain/<name>/prebuilt` and `$NDK/prebuilt` may contains both 91"`linux-x86`" and "`linux-x86_64`" folders for Linux tools in 32-bit and 64-bit modes, 92respectively. The ndk-build script automatically chooses a 64-bit version of the 93toolchain if the host OS supports it. You can force the use of a 32-bit toolchain by 94using NDK_HOST_32BIT=1 either in your envorinment or on the ndk-build command-line. 95 96Note that 64-bit tools utilize host resources better (faster, handle larger 97programs, etc) and they should function identically to their 32-bit counterparts. 98Ie. 64-bit toolchains still generate 32-bit binaries for Android. 99 100 101V. Requirements: 102---------------- 103 104You need GNU Make 3.81 or later to use 'ndk-build' or the NDK in general. 105The build scripts will detect that you're using a non-compliant Make tool 106and will complain with an error message. 107 108If you have GNU Make 3.81 installed, but that it is not launched by the 109default 'make' command, define GNUMAKE in your environment to point to it 110before launching 'ndk-build'. For example: 111 112 GNUMAKE=/usr/local/bin/gmake ndk-build 113 114Or to make the change more permanent: 115 116 export GNUMAKE=/usr/local/bin/gmake 117 ndk-build 118 119Adapt to your shell and GNU Make 3.81 installation location. 120 121You may override other host prebuilt tools in $NDK/prebuilt/<OS>/bin 122with the following environment variables 123 124 NDK_HOST_AWK=<path-to-awk> 125 126 NDK_HOST_ECHO=<path-to-echo> 127 128 NDK_HOST_CMP=<path-to-cmp> 129 130 131VI. Internals: 132-------------- 133 134'ndk-build' itself is a tiny wrapper around GNU Make, its purpose is simply 135to invoke the right NDK build script, it is equivalent to; 136 137 $GNUMAKE -f $NDK/build/core/build-local.mk [parameters] 138 139Where '$GNUMAKE' points to GNU Make 3.81 or later, and $NDK points to your 140NDK installation directory. 141 142Use this knowledge if you want to invoke the NDK build script from other 143shell scripts (or even your own Makefiles). 144