ndk/docs/DEVELOPMENT.html

   1 <html><body><pre>NDK Development:
   2 ----------------
   3
   4 This document describes how one can modify the NDK and generate
   5 new experimental release packages for it.
   6
   7 I. Getting the sources:
   8 =======================
   9
  10 The sources live under the "ndk" and "development/ndk" directories in
  11 the Android source tree:
  12
  13   - "ndk" contains the main build scripts and documentation
  14   - "development/ndk" contains platform-specific headers and samples
  15
  16 If you have downloaded the full Android source tree through the "repo"
  17 tool, you can start directly there. Otherwise, you can just get these
  18 two repositories with the following:
  19
  20   mkdir workdir
  21   cd workdir
  22   git clone git://android.git.kernel.org/platform/ndk.git ndk
  23   git clone git://android.git.kernel.org/platform/development.git development
  24   export NDK=`pwd`/ndk
  25
  26
  27 II. Building the platforms tree:
  28 ================================
  29
  30 You need to do that once if you want to use the content of $NDK to build
  31 samples, tests or anything else:
  32
  33   $NDK/build/tools/build-platforms.sh
  34
  35 What the script does is populate the $NDK/platforms and $NDK/samples
  36 directories from the content of development/ndk.
  37
  38 What is under development/ndk is segregated by API level. This makes it
  39 easier to add a new platform to the tree, but is not well-suited to building
  40 stuff. The build-platforms.sh script will gather all files appropriately
  41 and place the result inside $NDK/platforms and $NDK/samples.
  42
  43 Note: These directories are listed by $NDK/.gitignore, so they won't appear
  44       on your git status. You can remove them if you want by running:
  45
  46         $NDK/build/tools/dev-cleanup.sh
  47
  48       which also removes all intermediate files and directories from $NDK.
  49
  50
  51 III. Prebuilt binaries:
  52 =======================
  53
  54 The NDK requires several prebuilt binary executables to work properly, these
  55 include the following:
  56
  57   - toolchain binaries for the cross-compiler and associated tools
  58   - gdbserver binaries required for native debugging
  59
  60 These are not provided in the NDK's git repositories. However, there are
  61 several ways to get them:
  62
  63   1/ From a previous NDK release package:
  64
  65       By far the easiest thing to do is to copy the binaries from a previous
  66       NDK installation. You can do that with a command like the following one:
  67
  68             cp -r $PREVIOUS_NDK/toolchains/* $NDK/toolchains/
  69
  70       NOTE: The binaries are listed in $NDK/.gitignore and will not appear
  71             in your git status.
  72
  73
  74   2/ Download and rebuild directly from the internet:
  75
  76       IMPORTANT: This is *very* long.
  77
  78       The NDK comes with several scripts that can be used to rebuild the
  79       binaries from scratch, after downloading their sources from
  80       android.git.kernel.org.
  81
  82       There are several ways to do that, the most naive one, which will
  83       always work but will be *very* long (expect a few hours on a typical
  84       dual-core machine) is to do the following:
  85
  86         $NDK/build/tools/rebuild-all-prebuilt.sh
  87
  88       This will perform all the steps required to rebuild the binaries,
  89       which include:
  90
  91         - downloading the sources from android.git.kernel.org
  92         - patching them with appropriate changes, if needed
  93         - rebuilding everything from scratch
  94         - copying the generated binaries to the proper location under $NDK
  95
  96       You will need about 30G of free space in your /tmp directory to be
  97       able to do that, and *plenty* of free time.
  98
  99       IMPORTANT: If you plan to generate NDK release packages, even
 100       experimental ones, we strongly suggest you to use the individual
 101       steps described in 3/ below.
 102
 103       IMPORTANT:
 104           Since NDK r5, Windows binaries can be built on Linux by using the
 105           --mingw option, which requires that you have the "mingw32" package
 106           installed on your system. For example:
 107
 108               $NDK/build/tools/rebuild-all-prebuilt.sh --mingw
 109
 110           We do not officially support building these binaries directly on
 111           Windows (either through Cygwin or MSys) anymore, due to the vast
 112           number of problems these environments create when trying to do so.
 113
 114
 115
 116   3/ Download, rebuild, package, install in separate steps:
 117
 118       If you plan to generate your own NDK release packages, it is better
 119       to rebuild your binaries using separate steps, as in:
 120
 121          - Download the sources from the Internet, patch them, then
 122            package the result in a simple tarball.
 123
 124          - For every target system (linux-x86, darwin-x86 and windows),
 125            rebuild the binaries from the same source tarball.
 126
 127          - Package and collect all prebuilt binaries into a single
 128            directory that will be used when packaging NDK releases.
 129
 130       Here are more details on how to do that:
 131
 132       3.a/ Download + patching + packaging sources:
 133
 134         Use the following command to download, patch and package the
 135         sources:
 136
 137            $NDK/build/tools/download-toolchain-sources.sh --package
 138
 139         This will create a large tarball containing all sources ready to be
 140         used by the following step. The generated file path will be dumped at
 141         the script when it completes its operation and should be something
 142         like:
 143
 144           /tmp/android-ndk-toolchain-&lt;date&gt;.tar.bz2
 145
 146         Note that if you don't use the --package option, you will need to
 147         provide the name of a directory where the patched sources will be
 148         copied instead, as in:
 149
 150             $NDK/build/tools/download-toolchain-sources.sh &lt;target-src-dir&gt;
 151
 152
 153        3.b/ Build the binaries:
 154
 155         Use the following command to rebuild the binaries from the source
 156         tarball that was created in the previous section with the --package
 157         option:
 158
 159             $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-pkg=&lt;file&gt;
 160
 161         Where &lt;file&gt; points to the package generated by the
 162         download-toolchain-sources.sh script.
 163
 164         In the case where you downloaded the sources to a directory instead,
 165         use the --toolchain-src-dir option instead, as with:
 166
 167             $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-src-dir=&lt;path&gt;
 168
 169         This will rebuild all the prebuilt binaries for your host platforms
 170         and place them in a directory named:
 171
 172              /tmp/ndk-prebuilt/prebuilt-&lt;date&gt;/
 173
 174         These binary packages include the following:
 175
 176             - host-specific toolchain binaries. e.g.
 177                 arm-eabi-4.4.0-linux-x86.tar.bz2
 178
 179             - toolchain specific device binaries, e.g.
 180                 arm-eabi-4.4.0-gdbserver.tar.bz2
 181
 182         IMPORTANT:
 183             To generate Windows binaries on Windows, install the "mingw32"
 184             package on your system, then use the --mingw option, as in:
 185
 186                $NDK/build/tools/rebuild-all-prebuilt.sh --mingw --toolchain-pkg=&lt;file&gt;
 187
 188             Note that device-specific binaries (e.g. gdbserver) cannot be
 189             rebuilt with this option.
 190
 191        3.c/ Copy the binaries to your NDK tree:
 192
 193         Simply go to your NDK tree, and unpack the binary tarballs in place,
 194         for example:
 195
 196             cd $NDK
 197             tar xjf &lt;path&gt;/*.tar.bz2
 198
 199         Where &lt;path&gt; is a directory containing all the tarballs (e.g. it
 200         could be simply /tmp/ndk-prebuilt/prebuilt-&lt;date&gt;)
 201
 202         This will put the corresponding files at the correct location.
 203
 204
 205        3.c/
 206
 207       It is a good idea to save the generated toolchain binaries into
 208       an archive. To do that, use the --package option, as in:
 209
 210         $NDK/build/tools/rebuild-all-prebuilt.sh --package
 211
 212       This will generate a package file containing all the prebuilts, that
 213       can be unpacked directly into your $NDK directory. The package name is
 214       printed at the end, e.g."android-ndk-prebuild-&lt;date&gt;-&lt;system&gt;.tar.bz2".
 215
 216       Where &lt;date&gt; is the current date, and &lt;system&gt; is your system name.
 217       Then, to unpack:
 218
 219         cd $NDK                               k
 220         tar xjf /tmp/android-ndk-prebuilt-&lt;date&gt;-&lt;system&gt;.tar.bz2
 221
 222
 223       The generated package can easily be shared with other people.
 224
 225
 226 IV. Generate new package releases:
 227 ==================================
 228
 229 You can generate new experimental NDK release packages once you're satisfied
 230 with your changes, in order to share them with other people. There are two
 231 ways to do that:
 232
 233   1/ Using the 'make-release.sh' script:
 234
 235     The simplest, and also the slowest way, to generate a new NDK release
 236     is to invoke this script, with:
 237
 238         $NDK/build/tools/make-release.sh
 239
 240     NOTE: THIS WILL BE VERY VERY LONG. The script will do all the steps
 241           described in section III *from* scratch, and this can take several
 242           hours on a dual-core machine.
 243
 244     You should only use it in case of desperation, or if you don't want
 245     to deal with all the details exposed in section III or below.
 246
 247
 248   1/ Using a previous NDK release package:
 249
 250     This is the second simplest way to generate a new package, and it will
 251     be extremely quick because it will pick the prebuilt binaries directly
 252     from the previous package.
 253
 254     Do the following:
 255
 256         cd $NDK
 257         build/tools/package-release.sh --prebuilt-ndk=&lt;file&gt;
 258
 259     Where &lt;file&gt; points to a previous NDK package (i.e. archive file).
 260
 261     NOTE: This method can only be used to generate a single release package
 262           for the current host system.
 263
 264   2/ Using prebuilt tarballs:
 265
 266     If you have generated prebuilt binary tarballs with the steps described
 267     in section III.3 above, you can use these to generate release packages
 268     as well.
 269
 270     Assuming that you have collected prebuilt tarballs for all three supported
 271     host systems (i.e. linux-x86, darwin-x86 and windows) under a directory,
 272     do the following:
 273
 274         cd $NDK
 275         build/tools/package-release.sh --prebuilt-dir=&lt;path&gt;
 276
 277     The generated NDK package release will have a name that looks like:
 278
 279         /tmp/ndk-release/android-ndk-&lt;release&gt;-&lt;system&gt;.zip
 280
 281     Where &lt;release&gt; is by default the current date in ISO format
 282     (e.g. 20100915), and &lt;system&gt; corresponds to the host system where the
 283     NDK release is supposed to run.
 284
 285     The script 'package-release.sh' provides a few additional options:
 286
 287         --release=&lt;name&gt;       Change the name of the release
 288
 289         --systems=&lt;list&gt;       Change the list of host systems to package for
 290
 291         --platforms=&lt;list&gt;     List of API levels to package in the NDK
 292
 293         --out-dir=&lt;path&gt;       Specify a different output directory for the
 294                                final packages (instead of /tmp/ndk-release)
 295
 296     Use --help to list them all.
 297
 298 </pre></body></html>