AI 143665: am: CL 143491 ADT #1742875: Document the SDK build process and new cupcake SDK changes.
Original author: raphael
Merged from: //branches/cupcake/...
Automated import of CL 143665
diff --git a/docs/howto_build_SDK.txt b/docs/howto_build_SDK.txt
new file mode 100644
index 0000000..4b6507d
--- /dev/null
+++ b/docs/howto_build_SDK.txt
@@ -0,0 +1,280 @@
+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-
+