| Subject: How to build an Android SDK & ADT Eclipse plugin. |
| Date: 2009/03/27 |
| |
| |
| Table of content: |
| 0- License |
| 1- Foreword |
| 2- Building an SDK for MacOS and Linux |
| 3- Building an SDK for Windows |
| 4- Building an ADT plugin for Eclipse |
| 5- Conclusion |
| |
| |
| |
| ---------- |
| 0- License |
| ---------- |
| |
| Copyright (C) 2009 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
| |
| |
| ----------- |
| 1- Foreword |
| ----------- |
| |
| This document explains how to build the Android SDK and the ADT Eclipse plugin. |
| |
| It is designed for advanced users which are proficient with command-line |
| operations and know how to setup the pre-required software. |
| |
| Basically it's not trivial yet when done right it's not that complicated. |
| |
| |
| |
| -------------------------------------- |
| 2- Building an SDK for MacOS and Linux |
| -------------------------------------- |
| |
| First, setup your development environment and get the Android source code from |
| git as explained here: |
| |
| http://source.android.com/download |
| |
| For example for the cupcake branch: |
| |
| $ mkdir ~/my-android-git |
| $ cd ~/my-android-git |
| $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake |
| $ repo sync |
| |
| Then once you have all the source, simply build the SDK using: |
| |
| $ cd ~/my-android-git |
| $ . build/envsetup.sh |
| $ make sdk |
| |
| This will take a while, maybe between 20 minutes and several hours depending on |
| your machine. After a while you'll see this in the output: |
| |
| Package SDK: out/host/darwin-x86/sdk/android-sdk_eng.<build-id>_mac-x86.zip |
| |
| Some options: |
| |
| - Depending on your machine you can tell 'make' to build more things in |
| parallel, e.g. if you have a dual core, use "make -j4 sdk" to build faster. |
| |
| - You can define "BUILD_NUMBER" to control the build identifier that gets |
| incorporated in the resulting archive. The default is to use your username. |
| One suggestion is to include the date, e.g.: |
| |
| $ export BUILD_NUMBER=${USER}-`date +%Y%m%d-%H%M%S` |
| |
| There are certain characters you should avoid in the build number, typically |
| everything that might confuse 'make' or your shell. So for example avoid |
| punctuation and characters like $ & : / \ < > , and . |
| |
| |
| |
| ------------------------------ |
| 3- Building an SDK for Windows |
| ------------------------------ |
| |
| A- SDK pre-requisite |
| -------------------- |
| |
| First you need to build an SDK for MacOS and Linux. The Windows build works by |
| updating an existing MacOS or Linux SDK zip file and replacing the unix |
| binaries by Windows binaries. |
| |
| |
| |
| B- Cygwin pre-requisite & code checkout |
| --------------------------------------- |
| |
| Second you need to install Cygwin and configure it: |
| - Get the installer at http://sources.redhat.com/cygwin/ |
| - When installing Cygwin, set Default Text File Type to Unix/binary, not DOS/text. |
| This is really important, otherwise you will get errors when trying to |
| checkout code using git. |
| - Packages that you must install or not: |
| - Required packages: autoconf, bison, curl, flex, gcc, g++, git, gnupg, make, |
| mingw-zlib, python, zip, unzip. |
| - Suggested extra packages: diffutils, emacs, openssh, rsync, vim, wget. |
| - Packages that must not be installed: readline. |
| |
| Once you installed Cygwin properly, checkout the code from git as you did |
| for MacOS or Linux. Make sure to get the same branch, and if possible keep |
| it as close to the other one as possible: |
| |
| $ mkdir ~/my-android-git |
| $ cd ~/my-android-git |
| $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake |
| $ repo sync |
| |
| |
| |
| C- Building the Windows SDK |
| --------------------------- |
| |
| Now it's time to build that Windows SDK. You need: |
| - The path to the MacOS or Linux SDK zip. |
| - A directory where to place the final SDK. It will also hold some temporary |
| files. |
| - The build number will be extracted from the SDK zip filename, but this will |
| only work if that build number has no underscores in it. It is suggested you |
| just define SDK_NUMBER (and not BUILD_NUMBER!) on the command line before |
| invoking the script. |
| |
| Note that the "SDK number" is really a free identifier of your choice. It |
| doesn't need to be strictly a number. As always it is suggested you avoid |
| too much punctuation and special shell/make characters. Underscores cannot |
| be used. |
| |
| |
| To summarize, the steps on the command line would be something like this: |
| |
| $ mkdir ~/mysdk |
| $ export SDK_NUMBER=${USER}-`date +%Y%m%d-%H%M%S` |
| $ cd ~/my-android-git |
| $ development/build/tools/make_windows_sdk.sh /path/to/macos/or/linux/sdk.zip ~/mysdk |
| |
| This will take a while to build some Windows-specific binaries, including the |
| emulator, unzip the previous zip, rename & replace things and rezip the final |
| Windows SDK zip file. A typical build time should be around 5-10 minutes. |
| |
| |
| |
| ------------------------------------- |
| 4- Building an ADT plugin for Eclipse |
| ------------------------------------- |
| |
| Requirements: |
| - You can currently only build an ADT plugin for Eclipse under Linux. |
| - You must have a working version of Eclipse 3.4 "ganymede" RCP installed. |
| - You need X11 to run Eclipse at least once. |
| - You need a lot of patience. The trick is to do the initial setup correctly |
| once, after it's a piece of cake. |
| |
| |
| |
| A- Pre-requisites |
| ----------------- |
| |
| Note for Ubuntu or Debian users: your apt repository probably only has Eclipse |
| 3.2 available and it's probably not suitable to build plugins in the first |
| place. Forget that and install a working 3.4 manually as described below. |
| |
| - Visit http://www.eclipse.org/downloads/ to grab the |
| "Eclipse for RCP/Plug-in Developers (176 MB)" download for Linux. |
| 32-bit and 64-bit versions are available, depending on your Linux installation. |
| |
| Note: we've always used a 32-bit one, so use the 64-bit one at your own risk. |
| |
| Note: Eclipse comes in various editions. Do yourself a favor and just stick |
| to the RCP for building this plugin. For example the J2EE contains too many |
| useless features that will get in the way, and the "Java" version lacks some |
| plugins you need to build other plugins. Please just use the RCP one. |
| |
| - Unpack "eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz" in the directory of |
| your choice, e.g.: |
| |
| $ mkdir ~/eclipse-3.4 |
| $ cd ~/eclipse-3.4 |
| $ tar xvzf eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz |
| |
| This will create an "eclipse" directory in the current directory. |
| |
| - Set ECLIPSE_HOME to that "eclipse" directory: |
| |
| $ export ECLIPSE_HOME=~/eclipse-3.4/eclipse |
| |
| Note: it is important you set ECLIPSE_HOME before starting the build. |
| Otherwise the build process will try to download and install its own Eclipse |
| installation in /buildroot, which is probably limited to root. |
| |
| - Now, before you can build anything, it is important that you start Eclipse |
| *manually* once using the same user that you will use to build later. That's |
| because your Eclipse installation is not finished: Eclipse must be run at |
| least once to create some files in ~/.eclipse/. So run Eclipse now: |
| |
| $ ~/eclipse-3.4/eclipse/eclipse & |
| |
| Wait for it load, create a workspace when requested and then simply quit |
| using the File > Quit menu. That's it. You won't need to run it manually |
| again. |
| |
| |
| |
| B- Building ADT |
| --------------- |
| |
| Finally, you have Eclipse, it's installed and it created its own config files, |
| so now you can build your ADT plugin. To do that you'll change directories to |
| your git repository and invoke the build script by giving it a destination |
| directory and an optional build number: |
| |
| $ mkdir ~/mysdk |
| $ cd ~/my-android-git # <-- this is where you did your "repo sync" |
| $ development/tools/eclipse/scripts/build_server.sh ~/mysdk $USER |
| |
| The first argument is the destination directory. It must be absolute. Do not |
| give a relative destination directory such as "../mysdk". This will make the |
| Eclipse build fail with a cryptic message: |
| |
| BUILD SUCCESSFUL |
| Total time: 1 minute 5 seconds |
| **** Package in ../mysdk |
| Error: Build failed to produce ../mysdk/android-eclipse |
| Aborting |
| |
| The second argument is the build "number". The example used "$USER" but it |
| really is a free identifier of your choice. It cannot contain spaces nor |
| periods (dashes are ok.) If the build number is missing, a build timestamp will |
| be used instead in the filename. |
| |
| The build should take something like 5-10 minutes. |
| |
| |
| When the build succeeds, you'll see something like this at the end of the |
| output: |
| |
| ZIP of Update site available at ~/mysdk/android-eclipse-v200903272328.zip |
| or |
| ZIP of Update site available at ~/mysdk/android-eclipse-<buildnumber>.zip |
| |
| When you load the plugin in Eclipse, its feature and plugin name will look like |
| "com.android.ide.eclipse.adt_0.9.0.v200903272328-<buildnumber>.jar". The |
| internal plugin ID is always composed of the package, the build timestamp and |
| then your own build identifier (a.k.a. the "build number"), if provided. This |
| means successive builds with the same build identifier are incremental and |
| Eclipse will know how to update to more recent ones. |
| |
| |
| |
| ------------- |
| 5- Conclusion |
| ------------- |
| |
| This completes the howto guide on building your own SDK and ADT plugin. |
| Feedback is welcome on the public Android Open Source forums: |
| http://source.android.com/discuss |
| |
| If you are upgrading from a pre-cupcake to a cupcake or later SDK please read |
| the accompanying document "howto_use_cupcake_sdk.txt". |
| |
| -end- |
| |