1Copyright (C) 2009 The Android Open Source Project 2 3Licensed under the Apache License, Version 2.0 (the "License"); 4you may not use this file except in compliance with the License. 5You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9Unless required by applicable law or agreed to in writing, software 10distributed under the License is distributed on an "AS IS" BASIS, 11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12See the License for the specific language governing permissions and 13limitations under the License. 14 15 16Subject: How to build an Android SDK & ADT Eclipse plugin. 17Date: 2009/03/27 18Updated: 2010/03/30 19 20 21Table 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---------- 320- 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----------- 521- Foreword 53----------- 54 55This document explains how to build the Android SDK and the ADT Eclipse plugin. 56 57It is designed for advanced users which are proficient with command-line 58operations and know how to setup the pre-required software. 59 60Basically it's not trivial yet when done right it's not that complicated. 61 62 63 64-------------------------------------- 652- Building an SDK for MacOS and Linux 66-------------------------------------- 67 68First, setup your development environment and get the Android source code from 69git as explained here: 70 71 http://source.android.com/source/download.html 72 73For example for the cupcake branch: 74 75 $ mkdir ~/my-android-git 76 $ cd ~/my-android-git 77 $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake 78 $ repo sync 79 80Then 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 87This will take a while, maybe between 20 minutes and several hours depending on 88your 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 92Some 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------------------------------ 1103- Building an SDK for Windows 111------------------------------ 112 113A- SDK pre-requisite 114-------------------- 115 116First you need to build an SDK for MacOS and Linux. The Windows build works by 117updating an existing MacOS or Linux SDK zip file and replacing the unix 118binaries by Windows binaries. 119 120 121 122B- Cygwin pre-requisite & code checkout 123--------------------------------------- 124 125You must have Cygwin installed. But wait! You CANNOT use the latest Cygwin 1.7. 126Instead you MUST use the "legacy Cygwin 1.5" that you can find at this page: 127 128 http://cygwin.org/win-9x.html 129 130Don't mind the page title, just grab setup-legacy.exe and it will works just fine 131under XP or Vista. 132 133 134Now configure it: 135- When installing Cygwin, set Default Text File Type to Unix/binary, not DOS/text. 136 This is really important, otherwise you will get errors when trying to 137 checkout code using git. 138- Packages that you must install or not: 139 - Required packages: autoconf, bison, curl, flex, gcc, g++, git, gnupg, make, 140 mingw-zlib, python, zip, unzip. 141 - Suggested extra packages: diffutils, emacs, openssh, rsync, vim, wget. 142 - Packages that must not be installed: readline. 143 144Once you installed Cygwin properly, checkout the code from git as you did 145for MacOS or Linux. Make sure to get the same branch, and if possible keep 146it as close to the other one as possible: 147 148 $ mkdir ~/my-android-git 149 $ cd ~/my-android-git 150 $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake 151 $ repo sync 152 153 154 155C- Building the Windows SDK 156--------------------------- 157 158Now it's time to build that Windows SDK. You need: 159- The path to the MacOS or Linux SDK zip. 160- A directory where to place the final SDK. It will also hold some temporary 161 files. 162- The build number will be extracted from the SDK zip filename, but this will 163 only work if that build number has no underscores in it. It is suggested you 164 just define SDK_NUMBER (and not BUILD_NUMBER!) on the command line before 165 invoking the script. 166 167 Note that the "SDK number" is really a free identifier of your choice. It 168 doesn't need to be strictly a number. As always it is suggested you avoid 169 too much punctuation and special shell/make characters. Underscores cannot 170 be used. 171 172 173To summarize, the steps on the command line would be something like this: 174 175 $ mkdir ~/mysdk 176 $ export SDK_NUMBER=${USER}-`date +%Y%m%d-%H%M%S` 177 $ cd ~/my-android-git 178 $ development/build/tools/make_windows_sdk.sh /path/to/macos/or/linux/sdk.zip ~/mysdk 179 180This will take a while to build some Windows-specific binaries, including the 181emulator, unzip the previous zip, rename & replace things and rezip the final 182Windows SDK zip file. A typical build time should be around 5-10 minutes. 183 184 185 186------------------------------------- 1874- Building an ADT plugin for Eclipse 188------------------------------------- 189 190Requirements: 191- You can currently only build an ADT plugin for Eclipse under Linux. 192- You must have a working version of Eclipse 3.4 "ganymede" RCP installed. 193- You need X11 to run Eclipse at least once. 194- You need a lot of patience. The trick is to do the initial setup correctly 195 once, after it's a piece of cake. 196 197 198 199A- Pre-requisites 200----------------- 201 202Note for Ubuntu or Debian users: your apt repository probably only has Eclipse 2033.2 available and it's probably not suitable to build plugins in the first 204place. Forget that and install a working 3.4 manually as described below. 205 206- Visit http://www.eclipse.org/downloads/ to grab the 207 "Eclipse for RCP/Plug-in Developers (176 MB)" download for Linux. 208 32-bit and 64-bit versions are available, depending on your Linux installation. 209 210 Note: we've always used a 32-bit one, so use the 64-bit one at your own risk. 211 212 Note: Eclipse comes in various editions. Do yourself a favor and just stick 213 to the RCP for building this plugin. For example the J2EE contains too many 214 useless features that will get in the way, and the "Java" version lacks some 215 plugins you need to build other plugins. Please just use the RCP one. 216 217- Unpack "eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz" in the directory of 218 your choice, e.g.: 219 220 $ mkdir ~/eclipse-3.4 221 $ cd ~/eclipse-3.4 222 $ tar xvzf eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz 223 224 This will create an "eclipse" directory in the current directory. 225 226- Set ECLIPSE_HOME to that "eclipse" directory: 227 228 $ export ECLIPSE_HOME=~/eclipse-3.4/eclipse 229 230 Note: it is important you set ECLIPSE_HOME before starting the build. 231 Otherwise the build process will try to download and install its own Eclipse 232 installation in /buildroot, which is probably limited to root. 233 234- Now, before you can build anything, it is important that you start Eclipse 235 *manually* once using the same user that you will use to build later. That's 236 because your Eclipse installation is not finished: Eclipse must be run at 237 least once to create some files in ~/.eclipse/. So run Eclipse now: 238 239 $ ~/eclipse-3.4/eclipse/eclipse & 240 241 Wait for it load, create a workspace when requested and then simply quit 242 using the File > Quit menu. That's it. You won't need to run it manually 243 again. 244 245 246 247B- Building ADT 248--------------- 249 250Finally, you have Eclipse, it's installed and it created its own config files, 251so now you can build your ADT plugin. To do that you'll change directories to 252your git repository and invoke the build script by giving it a destination 253directory and an optional build number: 254 255 $ mkdir ~/mysdk 256 $ cd ~/my-android-git # <-- this is where you did your "repo sync" 257 $ development/tools/eclipse/scripts/build_server.sh ~/mysdk $USER 258 259The first argument is the destination directory. It must be absolute. Do not 260give a relative destination directory such as "../mysdk". This will make the 261Eclipse build fail with a cryptic message: 262 263 BUILD SUCCESSFUL 264 Total time: 1 minute 5 seconds 265 **** Package in ../mysdk 266 Error: Build failed to produce ../mysdk/android-eclipse 267 Aborting 268 269The second argument is the build "number". The example used "$USER" but it 270really is a free identifier of your choice. It cannot contain spaces nor 271periods (dashes are ok.) If the build number is missing, a build timestamp will 272be used instead in the filename. 273 274The build should take something like 5-10 minutes. 275 276 277When the build succeeds, you'll see something like this at the end of the 278output: 279 280 ZIP of Update site available at ~/mysdk/android-eclipse-v200903272328.zip 281or 282 ZIP of Update site available at ~/mysdk/android-eclipse-<buildnumber>.zip 283 284When you load the plugin in Eclipse, its feature and plugin name will look like 285"com.android.ide.eclipse.adt_0.9.0.v200903272328-<buildnumber>.jar". The 286internal plugin ID is always composed of the package, the build timestamp and 287then your own build identifier (a.k.a. the "build number"), if provided. This 288means successive builds with the same build identifier are incremental and 289Eclipse will know how to update to more recent ones. 290 291 292 293------------- 2945- Conclusion 295------------- 296 297This completes the howto guide on building your own SDK and ADT plugin. 298Feedback is welcome on the public Android Open Source forums: 299 http://source.android.com/discuss 300 301If you are upgrading from a pre-cupcake to a cupcake or later SDK please read 302the accompanying document "howto_use_cupcake_sdk.txt". 303 304-end- 305 306