1page.title=ndk-build
2@jd:body
3
4<div id="qv-wrapper">
5    <div id="qv">
6      <h2>On this page</h2>
7
8      <ol>
9        <li><a href="#int">Internals</a></li>
10         <li><a href="#ifc">Invoking from the Command Line</a></li>
11         <li><a href="#6432">64-Bit and 32-Bit Toolchains</a></li>
12         <li><a href="#req">Requirements</a></li>
13          </ol>
14        </li>
15      </ol>
16    </div>
17  </div>
18
19<p>The {@code ndk-build} file is a shell script introduced in Android NDK r4. Its purpose
20is to invoke the right NDK build script.
21
22<h2 id="int">Internals</h2>
23
24<p>Running the {@code ndk-build} script is equivalent to running the following command:</p>
25
26<pre class="no-pretty-print">
27$GNUMAKE -f &lt;ndk&gt;/build/core/build-local.mk
28&lt;parameters&gt;
29</pre>
30
31<p><code>$GNUMAKE</code> points to GNU Make 3.81 or later, and
32<code>&lt;ndk&gt;</code> points to your NDK installation directory. You can use
33this information to invoke ndk-build from other shell scripts, or even your own
34make files.</p>
35
36<h2 id="ifc">Invoking from the Command Line</h2>
37<p>The {@code ndk-build} file lives in the top level the NDK installation directory. To run it
38from the command line, invoke it while in or under your application project directory.
39For example: </p>
40
41<pre class="no-pretty-print">
42cd &lt;project&gt;
43$ &lt;ndk&gt;/ndk-build
44</pre>
45
46<p>In this example, <code>&lt;project&gt;</code> points to your
47project’s root directory, and <code>&lt;ndk&gt;</code> is the directory where
48you installed the NDK.</p>
49
50<p><a class="anchor" id="options"></a> </p>
51<h3>Options</h3>
52<p>All parameters to ndk-build are passed directly to the underlying GNU {@code make}
53command that runs the NDK build scripts. Combine <code>ndk-build</code> and
54options in the form <code>ndk-build &lt;option&gt;</code>. For example: </p>
55
56<pre class="no-pretty-print">
57$ ndk-build clean
58</pre>
59
60<p>The following options are available:</p>
61<dl>
62  <dt>{@code clean}</dt>
63  <dd>Remove any previously generated binaries.</dd>
64  <dt>{@code V=1}</dt>
65  <dd>Launch build, and display build commands.<dd>
66  <dt>{@code -B}</dt>
67  <dd>Force a complete rebuild.</dd>
68  <dt>{@code -B V=1}</dt>
69  <dd>Force a complete rebuild, and display build commands.</dd>
70  <dt>{@code NDK_LOG=1}</dd>
71  <dd>Display internal NDK log messages (used for debugging the NDK itself).</dd>
72  <dt>{@code NDK_DEBUG=1}</dt>
73  <dd>Force a debuggable build (see <a href="#dvr">Table 1</a>).</dd>
74  <dt>{@code NDK_DEBUG=0}</dt>
75  <dd>Force a release build (see <a href="#dvr">Table 1</a>).</dd>
76  <dt>{@code NDK_HOST_32BIT=1}</dt>
77  <dd>Always use the toolchain in 32-bit mode (see <a href="#6432">64-bit and 32-bit
78  Toolchains</a>).</dd>
79  <dt>{@code NDK_APPLICATION_MK=<file>}</dt>
80  <dd>Build, using a specific <code>Application.mk</code> file pointed to by the
81  {@code NDK_APPLICATION_MK} variable.</dd>
82  <dt>{@code -C <project>}</dt>
83  <dd>Build the native code for the project path located at {@code <project>}. Useful if you
84  don't want to {@code cd} to it in your terminal.</dd>
85</dl>
86
87<p><a class="anchor" id="dvr"></a> </p>
88<h3>Debuggable versus Release builds</h3>
89<p>Use the <code>NDK_DEBUG</code> option and, in certain cases,
90{@code AndroidManifest.xml} to specify debug or release build,
91optimization-related behavior, and inclusion of symbols. Table 1 shows the
92results of each possible combination of settings.</p>
93<p><em>Table 1.</em> Results of <code>NDK_DEBUG</code> (command line) and
94<code>android:debuggable</code> (manifest) combinations.</p>
95<table>
96<tr>
97<th></th><th>NDK_DEBUG=0 </th><th>NDK_DEBUG=1</th><th>NDK_DEBUG not specified
98</th></tr>
99<tr>
100<td>android:debuggble="true" </td><td>Debug; Symbols; Optimized*1
101</td><td>Debug; Symbols; Not optimized*2 </td><td>(same as NDK_DEBUG=1)
102</td></tr>
103<tr>
104<td>android:debuggable="false"</td><td>Release; Symbols; Optimized
105</td><td>Release; Symbols; Not optimized</td><td>Release; No symbols;
106Optimized*3 </td></tr>
107</table>
108*1: Useful for profiling.<br>
109*2: Default for running <a href="{@docRoot}ndk/guides/ndk-gdb.html">{@code ndk-gdb}</a>.<br>
110*3: Default mode.<br>
111<br>
112<p class="note"><strong>Note:</strong> {@code NDK_DEBUG=0} is the equivalent of
113{@code APP_OPTIM=release}, and complies with the GCC {@code -O2} option. {@code NDK_DEBUG=1} is the
114equivalent of {@code APP_OPTIM=debug} in {@code Application.mk}, and complies with the GCC
115{@code -O0} option. For more information about {@code APP_OPTIM}, see
116<a href="{@docRoot}ndk/guides/application_mk.html">Application.mk</a>.</p>
117<p>The syntax on the command line is, for example: </p>
118
119<pre class="no-pretty-print">
120$ ndk-build NDK_DEBUG=1
121</pre>
122
123<p>If you are using build tools from prior to SDK r8, you must also modify your
124{@code AndroidManifest.xml} file to specify debug mode. The syntax for doing so resembles the
125following:</p>
126
127<pre class="no-pretty-print">&lt;application android:label="@string/app_name"
128android:debuggable="true"&gt;
129</pre>
130
131From SDK r8 onward, you do not need to touch {@code AndroidManifest.xml}. Building a debug package
132(e.g. with ant debug or the corresponding option of the ADT plugin) causes the tool automatically to
133pick the native debug files generated with {@code NDK_DEBUG=1}.
134
135
136<h2 id="6432">64-Bit and 32-Bit Toolchains</h2>
137<p>Some toolchains come with both 64-bit and 32-bit versions. For example,
138directories {@code <ndk>/toolchain/<name>/prebuilt/} and
139{@code <ndk>/prebuilt/} may contain both {@code linux-x86} and
140{@code linux-x86_64} folders for Linux tools in 32-bit and 64-bit modes,
141respectively. The ndk-build script automatically chooses a 64-bit version of
142the toolchain if the host OS supports it. You can force the use of a 32-bit
143toolchain by using {@code NDK_HOST_32BIT=1} either in your environment or
144on the ndk-build command line.</p>
145<p>Note that 64-bit tools utilize host resources better (for instance, they are faster, and handle
146larger programs), and they can still generate 32-bit binaries for Android.</p>
147
148<h2 id="req">Requirements</h2>
149<p>You need GNU Make 3.81 or later to use ndk-build or the NDK in general.
150The build scripts will detect a non-compliant Make tool, and generate an error
151message.</p>
152<p>If you have GNU Make 3.81 installed, but the default <code>make</code>
153command doesn’t launch it, define {@code GNUMAKE} in your environment to point to it
154before launching ndk-build. For example: </p>
155
156<pre class="no-pretty-print">
157$ export GNUMAKE=/usr/local/bin/gmake
158$ ndk-build
159</pre>
160
161<p>You can override other host prebuilt tools in {@code $NDK/prebuilt/<OS>/bin/}
162with the following environment variables: </p>
163
164<pre class="no-pretty-print">
165$ export NDK_HOST_AWK=&lt;path-to-awk&gt;
166$ export NDK_HOST_ECHO=&lt;path-to-echo&gt;
167$ export NDK_HOST_CMP=&lt;path-to-cmp&gt;
168</pre>
169