docs/howto_build_SDK.txt

   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 git://android.git.kernel.org/platform/manifest.git -b cupcake
  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 A- SDK pre-requisite
 114 --------------------
 115
 116 First you need to build an SDK for MacOS and Linux. The Windows build works by
 117 updating an existing MacOS or Linux SDK zip file and replacing the unix
 118 binaries by Windows binaries.
 119
 120
 121
 122 B- Cygwin pre-requisite & code checkout
 123 ---------------------------------------
 124
 125 You must have Cygwin installed. But wait! You CANNOT use the latest Cygwin 1.7.
 126 Instead you MUST use the "legacy Cygwin 1.5" that you can find at this page:
 127
 128   http://cygwin.org/win-9x.html
 129
 130 Don't mind the page title, just grab setup-legacy.exe and it will works just fine
 131 under XP or Vista.
 132
 133
 134 Now 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
 144 Once you installed Cygwin properly, checkout the code from git as you did
 145 for MacOS or Linux. Make sure to get the same branch, and if possible keep
 146 it 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
 155 C- Building the Windows SDK
 156 ---------------------------
 157
 158 Now 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
 173 To 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
 180 This will take a while to build some Windows-specific binaries, including the
 181 emulator, unzip the previous zip, rename & replace things and rezip the final
 182 Windows SDK zip file. A typical build time should be around 5-10 minutes.
 183
 184
 185
 186 -------------------------------------
 187 4- Building an ADT plugin for Eclipse
 188 -------------------------------------
 189
 190 Requirements:
 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
 199 A- Pre-requisites
 200 -----------------
 201
 202 Note for Ubuntu or Debian users: your apt repository probably only has Eclipse
 203 3.2 available and it's probably not suitable to build plugins in the first
 204 place. 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
 247 B- Building ADT
 248 ---------------
 249
 250 Finally, you have Eclipse, it's installed and it created its own config files,
 251 so now you can build your ADT plugin. To do that you'll change directories to
 252 your git repository and invoke the build script by giving it a destination
 253 directory 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
 259 The first argument is the destination directory. It must be absolute. Do not
 260 give a relative destination directory such as "../mysdk". This will make the
 261 Eclipse 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
 269 The second argument is the build "number". The example used "$USER" but it
 270 really is a free identifier of your choice. It cannot contain spaces nor
 271 periods (dashes are ok.) If the build number is missing, a build timestamp will
 272 be used instead in the filename.
 273
 274 The build should take something like 5-10 minutes.
 275
 276
 277 When the build succeeds, you'll see something like this at the end of the
 278 output:
 279
 280   ZIP of Update site available at ~/mysdk/android-eclipse-v200903272328.zip
 281 or
 282   ZIP of Update site available at ~/mysdk/android-eclipse-<buildnumber>.zip
 283
 284 When 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
 286 internal plugin ID is always composed of the package, the build timestamp and
 287 then your own build identifier (a.k.a. the "build number"), if provided. This
 288 means successive builds with the same build identifier are incremental and
 289 Eclipse will know how to update to more recent ones.
 290
 291
 292
 293 -------------
 294 5- Conclusion
 295 -------------
 296
 297 This completes the howto guide on building your own SDK and ADT plugin.
 298 Feedback is welcome on the public Android Open Source forums:
 299   http://source.android.com/discuss
 300
 301 If you are upgrading from a pre-cupcake to a cupcake or later SDK please read
 302 the accompanying document "howto_use_cupcake_sdk.txt".
 303
 304 -end-
 305