docs/howto_build_SDK.txt

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