The `ndk-build` script builds projects that use the NDK's Make-based build
system. There is more specific documentation for the
[Android.mk](https://developer.android.com/ndk/guides/android_mk) and
[Application.mk](https://developer.android.com/ndk/guides/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](https://www.gnu.org/software/make/manual/html_node/Parallel.html) 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 `-j`<var translate="no">N</var>
    modifier or selecting a smaller value for <var translate="no">N</var>, 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](https://developer.android.com/ndk/guides/ndk-build#dvr)).


`NDK_DEBUG=0`
:
    Force a release build (see [table 1](https://developer.android.com/ndk/guides/ndk-build#dvr)).


`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`](https://developer.android.com/ndk/guides/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](https://developer.android.com/ndk/guides/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](https://clang.llvm.org/docs/JSONCompilationDatabase.html).

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.