Home | History | Annotate | Download | only in docs 
      1 <html><body><pre>'ndk-build' Overview
      2 
      3 I. Usage:
      4 ---------
      5 
      6 The Android NDK r4 introduced a new tiny shell script, named 'ndk-build',
      7 to simplify building machine code.
      8 
      9 The script is located at the top-level directory of the NDK, and shall
     10 be invoked from the command-line when in your application project
     11 directory, or any of its sub-directories. For example:
     12 
     13     cd $PROJECT
     14     $NDK/ndk-build
     15 
     16 Where $NDK points to your NDK installation path. You can also create an
     17 alias or add $NDK to your PATH to avoid typing it every time.
     18 
     19 
     20 II. Options:
     21 ------------
     22 
     23 All parameters to 'ndk-build' are passed directly to the underlying GNU Make
     24 command that runs the NDK build scripts. Notable uses include:
     25 
     26   ndk-build                  --&gt; rebuild required machine code.
     27   ndk-build clean            --&gt; clean all generated binaries.
     28 
     29   ndk-build NDK_DEBUG=1      --&gt; generate debuggable native code.
     30 
     31   ndk-build V=1              --&gt; launch build, displaying build commands.
     32 
     33   ndk-build -B               --&gt; force a complete rebuild.
     34 
     35   ndk-build -B V=1           --&gt; force a complete rebuild and display build
     36                                  commands.
     37 
     38   ndk-build NDK_LOG=1        --&gt; display internal NDK log messages
     39                                  (used for debugging the NDK itself).
     40 
     41   ndk-build NDK_DEBUG=1      --&gt; force a debuggable build (see below)
     42   ndk-build NDK_DEBUG=0      --&gt; force a release build (see below)
     43 
     44   ndk-build NDK_APPLICATION_MK=&lt;file&gt;
     45     --&gt; rebuild, using a specific Application.mk pointed to by
     46         the NDK_APPLICATION_MK command-line variable.
     47 
     48   ndk-build -C &lt;project&gt;     --&gt; build the native code for the project
     49                                  path located at &lt;project&gt;. Useful if you
     50                                  don't want to 'cd' to it in your terminal.
     51 
     52 
     53 III. Debuggable versus Release builds:
     54 --------------------------------------
     55 
     56 In NDK r5, ndk-build has been modified to make it easier to switch between
     57 release and debug builds. This is done by using the NDK_DEBUG variable.
     58 For example:
     59 
     60   $NDK/ndk-build NDK_DEBUG=1  =&gt; forces the generation of debug binaries
     61   $NDK/ndk-build NDK_DEBUG=0  =&gt; forces the generation of release binaries
     62 
     63 If you don't specify NDK_DEBUG, ndk-build will keep its default behaviour,
     64 which is to inspect the AndroidManifest.xml, if any, and see if its
     65 &lt;application&gt; element has android:debuggable="true".
     66 
     67 IMPORTANT: If you use the build tools of SDK r8 (or higher), you
     68            won't need to touch your AndroidManifest.xml file at all!
     69 
     70            That's because if you build a debug package (e.g. with
     71            "ant debug" or the corresponding option of the ADT plugin),
     72            the tool will  automatically pick the native debug files
     73            generated with NDK_DEBUG=1.
     74 
     75 Also, as a convenience, the release and debug object files generated by the
     76 NDK are now stored in different directories (e.g. obj/local/&lt;abi&gt;/objs and
     77 obj/local/&lt;abi&gt;/objs-debug). This avoids having to recompile all your sources
     78 when you switch between these two modes (even when you only modified one or
     79 two source files).
     80 
     81 
     82 IV. Requirements:
     83 -----------------
     84 
     85 You need GNU Make 3.81 or later to use 'ndk-build' or the NDK in general.
     86 The build scripts will detect that you're using a non-compliant Make tool
     87 and will complain with an error message.
     88 
     89 If you have GNU Make 3.81 installed, but that it is not launched by the
     90 default 'make' command, define GNUMAKE in your environment to point to it
     91 before launching 'ndk-build'. For example:
     92 
     93     GNUMAKE=/usr/local/bin/gmake ndk-build
     94 
     95 Or to make the change more permanent:
     96 
     97     export GNUMAKE=/usr/local/bin/gmake
     98     ndk-build
     99 
    100 Adapt to your shell and GNU Make 3.81 installation location.
    101 
    102 
    103 V. Internals:
    104 -------------
    105 
    106 'ndk-build' itself is a tiny wrapper around GNU Make, its purpose is simply
    107 to invoke the right NDK build script, it is equivalent to;
    108 
    109     $GNUMAKE -f $NDK/build/core/build-local.mk [parameters]
    110 
    111 Where '$GNUMAKE' points to GNU Make 3.81 or later, and $NDK points to your
    112 NDK installation directory.
    113 
    114 Use this knowledge if you want to invoke the NDK build script from other
    115 shell scripts (or even your own Makefiles).
    116 </pre></body></html>
    117