1 Copyright (C) 2009 The Android Open Source Project 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 15 16 Subject: How to build an Android SDK & ADT Eclipse plugin. 17 Date: 2009/03/27 18 Updated: 2010/03/30 19 20 21 Table of content: 22 0- License 23 1- Foreword 24 2- Building an SDK for MacOS and Linux 25 3- Building an SDK for Windows 26 4- Building an ADT plugin for Eclipse 27 5- Conclusion 28 29 30 31 ---------- 32 0- License 33 ---------- 34 35 Copyright (C) 2009 The Android Open Source Project 36 37 Licensed under the Apache License, Version 2.0 (the "License"); 38 you may not use this file except in compliance with the License. 39 You may obtain a copy of the License at 40 41 http://www.apache.org/licenses/LICENSE-2.0 42 43 Unless required by applicable law or agreed to in writing, software 44 distributed under the License is distributed on an "AS IS" BASIS, 45 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 46 See the License for the specific language governing permissions and 47 limitations under the License. 48 49 50 51 ----------- 52 1- Foreword 53 ----------- 54 55 This document explains how to build the Android SDK and the ADT Eclipse plugin. 56 57 It is designed for advanced users which are proficient with command-line 58 operations and know how to setup the pre-required software. 59 60 Basically it's not trivial yet when done right it's not that complicated. 61 62 63 64 -------------------------------------- 65 2- Building an SDK for MacOS and Linux 66 -------------------------------------- 67 68 First, setup your development environment and get the Android source code from 69 git as explained here: 70 71 http://source.android.com/source/download.html 72 73 For example for the cupcake branch: 74 75 $ mkdir ~/my-android-git 76 $ cd ~/my-android-git 77 $ repo init -u https://android.googlesource.com/platform/manifest -b master 78 $ repo sync 79 80 Then once you have all the source, simply build the SDK using: 81 82 $ cd ~/my-android-git 83 $ . build/envsetup.sh 84 $ lunch sdk-eng 85 $ make sdk 86 87 This will take a while, maybe between 20 minutes and several hours depending on 88 your machine. After a while you'll see this in the output: 89 90 Package SDK: out/host/darwin-x86/sdk/android-sdk_eng.<build-id>_mac-x86.zip 91 92 Some options: 93 94 - Depending on your machine you can tell 'make' to build more things in 95 parallel, e.g. if you have a dual core, use "make -j4 sdk" to build faster. 96 97 - You can define "BUILD_NUMBER" to control the build identifier that gets 98 incorporated in the resulting archive. The default is to use your username. 99 One suggestion is to include the date, e.g.: 100 101 $ export BUILD_NUMBER=${USER}-`date +%Y%m%d-%H%M%S` 102 103 There are certain characters you should avoid in the build number, typically 104 everything that might confuse 'make' or your shell. So for example avoid 105 punctuation and characters like $ & : / \ < > , and . 106 107 108 109 ------------------------------ 110 3- Building an SDK for Windows 111 ------------------------------ 112 113 Full Windows SDK builds are now only supported on Linux -- most of the framework is 114 not designed to be built on Windows so technically the Windows SDK is build on top 115 of a Linux SDK where a few binaries are replaced. So it cannot be built on Windows, 116 and it cannot be built on Mac, only on Linux. 117 118 I'll repeat this again because it's important: 119 120 To build the Android SDK for Windows, you need to use a *Linux* box. 121 122 A- Pre-requisites 123 ----------------- 124 125 Before you can even think of building the Android SDK for Windows, you need to 126 perform the steps from section "2- Building an SDK for MacOS and Linux" above: 127 setup and build a regular Linux SDK. Once this working, please continue here. 128 129 Under Ubuntu, you will need the following extra packages: 130 131 $ sudo apt-get install mingw32 tofrodos 132 133 mingw32 is the cross-compiler, tofrodos adds a unix2dos command 134 135 136 B- Building 137 ----------- 138 139 To build, perform the following steps: 140 141 $ . build/envsetup.sh 142 $ lunch sdk-eng 143 $ make win_sdk 144 145 Note that this will build both a Linux SDK then a Windows SDK. The result is located at 146 out/host/windows/sdk/android-sdk_eng.${USER}_windows/ 147 148 149 150 ---------------------------- 151 4- Partial SDK Windows Tools 152 ---------------------------- 153 154 As explained above, you can only build a *full* SDK for Windows using Linux. 155 However sometimes you need to develop one specific tools, e.g. adb.exe or 156 aapt.exe, and it's just more convenient to do it on the same platform where 157 you can actually test it. This is what this section explains. 158 159 160 A- Cygwin pre-requisite & code checkout 161 --------------------------------------- 162 163 You must have Cygwin installed. You can use the latest Cygwin 1.7 or the 164 the "legacy Cygwin 1.5" from: 165 166 http://cygwin.org/ 167 168 Now configure it: 169 - When installing Cygwin, set Default Text File Type to Unix/binary, not DOS/text. 170 This is really important, otherwise you will get errors when trying to 171 checkout code using git. 172 - Packages that you must install or not: 173 - Required packages: autoconf, bison, curl, flex, gcc, g++, git, gnupg, make, 174 mingw-zlib, python, zip, unzip. 175 - Suggested extra packages: diffutils, emacs, openssh, rsync, vim, wget. 176 - Packages that must not be installed: readline. 177 178 Once you installed Cygwin properly, checkout the code from git as you did 179 for MacOS or Linux (see section 2 above.) 180 181 182 183 C- Building the Windows Tools 184 ----------------------------- 185 186 This is the easy part: run make on the tool you want. 187 How do you know which tools you can build? Well obviously all the ones 188 that come in an installed SDK/tools or SDK/platform-tools folder! 189 190 Example, to build adb: 191 192 $ cd ~/my-android-git 193 $ . build/envsetup.sh 194 $ lunch sdk-eng 195 $ make adb 196 197 The result will be somewhere in out/host/windows-x86/bin/. Just look at 198 the output from make to get the exact path. Since you are building this 199 under cygwin, you get an unstripped binary that you can happily feed to 200 gdb to get debugger symbols: 201 202 $ gdb --args out/host/windows-x86/bin/adb.exe <adb arguments> 203 204 205 And before you ask, msys is not supported, nor is MSVC or windbg. 206 207 So you can build a lot of little parts of the SDK on Windows, one tool 208 at a time, but not the full thing because basically building the whole 209 platform is not supported. This means you cannot build "android.jar" 210 nor "layoutlib.jar" under Windows. For this you want Linux. 211 212 213 214 D- Building the Windows Tools on Linux 215 -------------------------------------- 216 217 You can also build isolated windows tools directly on Linux. 218 Again, it requires a checkout of the full android code and the usual 219 setup like described above to build an SDK. 220 221 Then to build an isolated Windows binary, you'd do something like this: 222 223 $ cd ~/my-android-git 224 $ . build/envsetup.sh 225 $ lunch sdk-eng 226 $ USE_MINGW=1 make adb 227 228 The special environment variable "USE_MINGW" must be set to 1. This is 229 the clue to switch the make logic to cross-compiling to Windows under 230 Linux. 231 232 233 234 ------------------------------------- 235 4- Building an ADT plugin for Eclipse 236 ------------------------------------- 237 238 Requirements: 239 - You can currently only build an ADT plugin for Eclipse under Linux. 240 - You must have a working version of Eclipse 3.6 "helios" RCP installed. 241 - You need X11 to run Eclipse at least once. 242 - You need a lot of patience. The trick is to do the initial setup correctly 243 once, after it's a piece of cake. 244 245 246 247 A- Pre-requisites 248 ----------------- 249 250 Note for Ubuntu or Debian users: your apt repository probably only has Eclipse 251 3.2 available and it's probably not suitable to build plugins in the first 252 place. Forget that and install a working 3.6 manually as described below. 253 254 - Visit http://www.eclipse.org/downloads/ to grab the 255 "Eclipse for RCP/Plug-in Developers (176 MB)" download for Linux. 256 32-bit and 64-bit versions are available, depending on your Linux installation. 257 258 Note: Eclipse comes in various editions. Do yourself a favor and just stick 259 to the RCP for building this plugin. For example the J2EE contains too many 260 useless features that will get in the way, and the "Java" version lacks some 261 plugins you need to build other plugins. Please just use the RCP one. 262 263 Note: You will need the CDT plugin but don't take a "CDT" flavor build as it 264 will lack the RCP tools. Instead take an RCP and then add CDT. 265 266 - Unpack "eclipse-rcp-*-linux-gtk.tar.gz" in the directory of 267 your choice, e.g.: 268 269 $ mkdir ~/eclipse-3.6 270 $ cd ~/eclipse-3.6 271 $ tar xvzf eclipse-rcp-????-linux-gtk.tar.gz 272 273 This will create an "eclipse" directory in the current directory. 274 275 - Set ECLIPSE_HOME to that "eclipse" directory: 276 277 $ export ECLIPSE_HOME=~/eclipse-3.6/eclipse 278 279 Note: it is important you set ECLIPSE_HOME before starting the build. 280 Otherwise the build process will try to download and install its own Eclipse 281 installation in /buildroot, which is probably limited to root. 282 283 - Now, before you can build anything, it is important that you start Eclipse 284 *manually* once using the same user that you will use to build later. That's 285 because your Eclipse installation is not finished: Eclipse must be run at 286 least once to create some files in ~/.eclipse/. So run Eclipse now: 287 288 $ ~/eclipse-3.6/eclipse/eclipse & 289 290 - Since you have Eclipse loaded, now is a perfect time to pick up the 291 CDT plugin. (Another alternative is is to fetch the CDT from its archives 292 and manually dump all the *.jar in eclipse/plugins.) 293 294 That's it. You won't need to run it manually again. 295 296 297 298 B- Building ADT 299 --------------- 300 301 Finally, you have Eclipse, it's installed and it created its own config files, 302 so now you can build your ADT plugin. To do that you'll change directories to 303 your git repository and invoke the build script by giving it a destination 304 directory and an optional build number: 305 306 $ mkdir ~/mysdk 307 $ cd ~/my-android-git # <-- this is where you did your "repo sync" 308 $ sdk/eclipse/scripts/build_server.sh ~/mysdk $USER 309 310 The first argument is the destination directory. It must be absolute. Do not 311 give a relative destination directory such as "../mysdk". This will make the 312 Eclipse build fail with a cryptic message: 313 314 BUILD SUCCESSFUL 315 Total time: 1 minute 5 seconds 316 **** Package in ../mysdk 317 Error: Build failed to produce ../mysdk/android-eclipse 318 Aborting 319 320 The second argument is the build "number". The example used "$USER" but it 321 really is a free identifier of your choice. It cannot contain spaces nor 322 periods (dashes are ok.) If the build number is missing, a build timestamp will 323 be used instead in the filename. 324 325 The build should take something like 5-10 minutes. 326 327 328 When the build succeeds, you'll see something like this at the end of the 329 output: 330 331 ZIP of Update site available at ~/mysdk/android-eclipse-v200903272328.zip 332 or 333 ZIP of Update site available at ~/mysdk/android-eclipse-<buildnumber>.zip 334 335 When you load the plugin in Eclipse, its feature and plugin name will look like 336 "com.android.ide.eclipse.adt_0.9.0.v200903272328-<buildnumber>.jar". The 337 internal plugin ID is always composed of the package, the build timestamp and 338 then your own build identifier (a.k.a. the "build number"), if provided. This 339 means successive builds with the same build identifier are incremental and 340 Eclipse will know how to update to more recent ones. 341 342 343 344 ------------- 345 5- Conclusion 346 ------------- 347 348 This completes the howto guide on building your own SDK and ADT plugin. 349 Feedback is welcome on the public Android Open Source forums: 350 http://source.android.com/discuss 351 352 If you are upgrading from a pre-cupcake to a cupcake or later SDK please read 353 the accompanying document "howto_use_cupcake_sdk.txt". 354 355 -end- 356 357
