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 Setting	NDK_DEBUG=0	NDK_DEBUG=1	NDK_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 optimized	Release; 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.