The ndk-build script

The ndk-build script builds projects that use the NDK's Make-based build system. There is more specific documentation for the Android.mk and Application.mk configuration used by ndk-build.

Internals

Running the ndk-build script is equivalent to running the following command:

$GNUMAKE -f <ndk>/build/core/build-local.mk
<parameters>

$GNUMAKE points to GNU Make 3.81 or later, and <ndk> points to your NDK installation directory. You can use this information to invoke ndk-build from other shell scripts, or even your own make files.

Invoke from the command line

The ndk-build script lives in the top level NDK installation directory. To run it from the command line, invoke it while in or under your application project directory. For example: 

$ cd <project>
$ <ndk>/ndk-build

In this example, <project> points to your project’s root directory, and <ndk> is the directory where you installed the NDK.

Options

All parameters to ndk-build are passed directly to the underlying GNU make command that runs the NDK build scripts. Combine ndk-build and options in the form ndk-build <option>. For example: 

$ ndk-build clean

The following options are available:

clean
Remove any previously generated binaries.

Note: On Mac OS X, running ndk-build clean with a high number of parallel executions may result in a build error that includes the following message: 

rm: fts_read: No such file or directory

To avoid this issue, consider not using the -jN modifier or selecting a smaller value for N, such as 2.

V=1
Launch build, and display build commands.
-B
Force a complete rebuild.
-B V=1
Force a complete rebuild, and display build commands.
NDK_LOG=1
Display internal NDK log messages (used for debugging the NDK itself).
NDK_DEBUG=1
Force a debuggable build (see table 1).
NDK_DEBUG=0
Force a release build (see table 1).
NDK_HOST_32BIT=1
Always use the toolchain in 32-bit mode.
NDK_APPLICATION_MK=<file>
Build, using a specific Application.mk file pointed to by the NDK_APPLICATION_MK variable.
-C <project>
Build the native code for the project path located at <project>. Useful if you don't want to cd to it in your terminal.

Debuggable versus release builds

Use the NDK_DEBUG option and, in certain cases, AndroidManifest.xml to specify debug or release build, optimization-related behavior, and inclusion of symbols. Table 1 shows the results of each possible combination of settings.

Table 1. Results of NDK_DEBUG (command line) and android:debuggable (manifest) combinations.

Manifest SettingNDK_DEBUG=0 NDK_DEBUG=1NDK_DEBUG not specified
android:debuggable="true" Debug; Symbols; Optimized*1 Debug; Symbols; Not optimized*2 (same as NDK_DEBUG=1)
android:debuggable="false"Release; Symbols; Optimized Release; Symbols; Not optimizedRelease; No symbols; Optimized*3
*1: Useful for profiling.
*2: Default for running ndk-gdb.
*3: Default mode.

Note: `NDK_DEBUG=0` is the equivalent of `APP_OPTIM=release`, and compiles with `-O2`. `NDK_DEBUG=1` is the equivalent of `APP_OPTIM=debug` in `Application.mk`, and compiles with `-O0`. For more information about `APP_OPTIM`, see Application.mk.

The syntax on the command line is, for example: 

$ ndk-build NDK_DEBUG=1

Requirements

You need GNU Make 4 to use ndk-build or the NDK in general. The NDK includes its own copy of GNU Make and will use that unless you've set the $GNUMAKE environment variable to point to an unsuitable make.

JSON compilation databases

In NDK r18 and newer, ndk-build can generate a JSON compilation database.

You can either use ndk-build compile_commands.json to generate the database without building your code, or ndk-build GEN_COMPILE_COMMANDS_DB=true if you want to build and generate the database as a side-effect.