NDK Programmer's Guide
|
Internals
Invoking from the Command Line
Invoking from Eclipse
64-bit and 32-bit toolchains
Requirements
ndk-build is a tiny shell script introduced in Android NDK r4. Its purpose is simply to invoke the right NDK build script; it is equivalent to:
$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.
ndk-build lives in the top-level directory of the NDK. 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. Per “Getting Started,” you can add $NDK to your PATH
to avoid having to type the whole filepath every time you use ndk-build.
Alternatively, you can create an alias.
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
V=1
-B
-B V=1
NDK_LOG=1
NDK_DEBUG=1
NDK_DEBUG=0
NDK_HOST_32BIT=1
NDK_APPLICATION_MK=<file>
Application.mk
file pointed to by the
NDK_APPLICATION_MK
variable.-C <project>
<project>
. Useful if you don't want to cd
to it
in your terminal.To build from Eclipse, make sure that you have configured it as described in
"Getting Started." If you
wish to build using the default ndk-build
command, with no
options, you can just build your project just as you would any Android project.
To add the options described above to the ndk-build
command that
Eclipse issues, follow these steps:
Preferences
.C/C++ Build
.Use default build command
.OK
.Figure 1. Specifying a debug build from within Eclipse
Use the NDK_DEBUG
parameter in conjunction with
AndroidManifest.xml to control whether to perform a 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.
NDK_DEBUG=0 | NDK_DEBUG=1 | NDK_DEBUG not specified | |
---|---|---|---|
android:debuggble="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=1 is the equivalent of APP_OPTIM= debug in Application.mk, and complies with the GCC -O0 option. NDK_DEBUG=0 is the equivalent of APP_OPTIM= release, and complies with GCC -O2. For more information about `APP_OPTIM`, see the Application.mk section.
The syntax on the command line is, for example:
$ ndk-build NDK_DEBUG=1
In the AndroidManifest.xml file
, the syntax resembles the
following:
<application android:label="@string/app_name" android:debuggable="true">
Important Note: If you use the build tools of SDK r8 (or higher), you need not need touch your AndroidManifest.xml file at all: Building a debug package (e.g. with ant debug or the corresponding option of the ADT plugin) causes the tool automatically to pick the native debug files generated with NDK_DEBUG=1.
Some toolchains come with both 64-bit and 32-bit versions. For example,
directories <ndk>/toolchain/<name>/prebuilt/
and
<ndk>/prebuilt/
may contain both linux-x86
and
linux-x86_64
folders for Linux tools in 32-bit and 64-bit modes,
respectively. The ndk-build script automatically chooses a 64-bit version of
the toolchain if the host OS supports it. You can force the use of a 32-bit
toolchain by using NDK_HOST_32BIT=1
either in your environment or
on the ndk-build
command line.
Note that 64-bit tools utilize host resources better (faster, handle larger programs, etc), and they can still generate 32-bit binaries for Android.
You need GNU Make 3.81 or later to use 'ndk-build' or the NDK in general. The build scripts will detect a non-compliant Make tool, and generate an error message.
If you have GNU Make 3.81 installed, but the default make
command doesn’t launch it, define GNUMAKE in your environment to point to it
before launching 'ndk-build'. For example:
$ export GNUMAKE=/usr/local/bin/gmake $ ndk-build
Adapt to your shell and GNU Make 3.81 installation location.
You may override other host prebuilt tools in $NDK/prebuilt/<OS>/bin/ with the following environment variables:
$ export NDK_HOST_AWK=<path-to-awk> $ export NDK_HOST_ECHO=<path-to-echo> $ export NDK_HOST_CMP=<path-to-cmp>