1 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 https://android.googlesource.com/platform/ndk.git ndk 23 git clone https://android.googlesource.com/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.googlesource.com. 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.googlesource.com 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-<date>.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 <target-src-dir> 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=<file> 160 161 Where <file> 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=<path> 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-<date>/ 173 174 These binary packages include the following: 175 176 - host-specific toolchain binaries. e.g. 177 `arm-linux-androideabi-4.6-linux-x86.tar.bz2`. 178 179 - toolchain specific device binaries, e.g. 180 `arm-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=<file> 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 <path>/*.tar.bz2 198 199 Where <path> is a directory containing all the tarballs (e.g. it 200 could be simply /tmp/ndk-prebuilt/prebuilt-<date>) 201 202 This will put the corresponding files at the correct location. 203 204 #### 3.c/ 205 206 It is a good idea to save the generated toolchain binaries into 207 an archive. To do that, use the --package option, as in: 208 209 $NDK/build/tools/rebuild-all-prebuilt.sh --package 210 211 This will generate a package file containing all the prebuilts, that 212 can be unpacked directly into your $NDK directory. The package name is 213 printed at the end, e.g."android-ndk-prebuild-<date>-<system>.tar.bz2". 214 215 Where <date> is the current date, and <system> is your system name. 216 Then, to unpack: 217 218 cd $NDK 219 tar xjf /tmp/android-ndk-prebuilt-<date>-<system>.tar.bz2 220 221 222 The generated package can easily be shared with other people. 223 224 225 IV. Generate new package releases: 226 --- 227 228 You can generate new experimental NDK release packages once you're satisfied 229 with your changes, in order to share them with other people. There are two 230 ways to do that: 231 232 ### 1. Using the 'make-release.sh' script: 233 234 The simplest, and also the slowest way, to generate a new NDK release 235 is to invoke this script, with: 236 237 $NDK/build/tools/make-release.sh 238 239 NOTE: THIS WILL BE VERY VERY LONG. The script will do all the steps 240 described in section III *from* scratch, and this can take several 241 hours on a dual-core machine. 242 243 You should only use it in case of desperation, or if you don't want 244 to deal with all the details exposed in section III or below. 245 246 247 ### 2. Using a previous NDK release package: 248 249 This is the second simplest way to generate a new package, and it will 250 be extremely quick because it will pick the prebuilt binaries directly 251 from the previous package. 252 253 Do the following: 254 255 cd $NDK 256 build/tools/package-release.sh --prebuilt-ndk=<file> 257 258 Where <file> points to a previous NDK package (i.e. archive file). 259 260 NOTE: This method can only be used to generate a single release package 261 for the current host system. 262 263 ### 3. Using prebuilt tarballs: 264 265 If you have generated prebuilt binary tarballs with the steps described 266 in section III.3 above, you can use these to generate release packages 267 as well. 268 269 Assuming that you have collected prebuilt tarballs for all three supported 270 host systems (i.e. linux-x86, darwin-x86 and windows) under a directory, 271 do the following: 272 273 cd $NDK 274 build/tools/package-release.sh --prebuilt-dir=<path> 275 276 The generated NDK package release will have a name that looks like: 277 278 /tmp/ndk-release/android-ndk-<release>-<system>.zip 279 280 Where <release> is by default the current date in ISO format 281 (e.g. 20100915), and <system> corresponds to the host system where the 282 NDK release is supposed to run. 283 284 The script 'package-release.sh' provides a few additional options: 285 286 --release=<name> Change the name of the release 287 288 --systems=<list> Change the list of host systems to package for 289 290 --platforms=<list> List of API levels to package in the NDK 291 292 --out-dir=<path> Specify a different output directory for the 293 final packages (instead of /tmp/ndk-release) 294 295 Use --help to list them all. 296
