am 9bad20b0: merge from froyo-plus-aosp
Merge commit '9bad20b019424a315c3f9a3d2b0e3a711bb43665' * commit '9bad20b019424a315c3f9a3d2b0e3a711bb43665': Moving SDK howto docs from development.git into sdk.git.
This commit is contained in:
The Android Open Source Project
committed by
Android Git Automerger
Android Git Automerger
commit
5b836a44c7
@@ -1,189 +0,0 @@
|
|||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
Subject: How to get the android source code using Cygwin and Git
|
|
||||||
Date: 2009/04/27
|
|
||||||
Updated: 2009/05/21
|
|
||||||
Updated: 2010/03/30
|
|
||||||
|
|
||||||
|
|
||||||
Table of content:
|
|
||||||
1- Goals and Requirements
|
|
||||||
2- Getting the code, the simple way
|
|
||||||
3- SSH issues
|
|
||||||
4- Advanced Tricks
|
|
||||||
|
|
||||||
|
|
||||||
-------------------------
|
|
||||||
1- Goals and Requirements
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
This document explains how to checkout the Android source from the git
|
|
||||||
repositories under Windows.
|
|
||||||
|
|
||||||
As stated in development/docs/howto_build_SDK.txt, one can't build the whole
|
|
||||||
Android source code under Windows. You can only build the SDK tools for
|
|
||||||
Windows.
|
|
||||||
|
|
||||||
There are a number of caveats in checking out the code from Git under Windows.
|
|
||||||
This document tries to explain them.
|
|
||||||
|
|
||||||
First you will need to meet the following requirements:
|
|
||||||
- You must have Cygwin installed. But wait! You CANNOT use the latest Cygwin 1.7.
|
|
||||||
Instead you MUST use the "legacy Cygwin 1.5" that you can find at this page:
|
|
||||||
|
|
||||||
http://cygwin.org/win-9x.html
|
|
||||||
|
|
||||||
Don't mind the page title, just grab setup-legacy.exe and it will works just fine
|
|
||||||
under XP or Vista.
|
|
||||||
|
|
||||||
- You must install Cyginw using the "Unix / Binary" mode.
|
|
||||||
If you don't do that, git will fail to properly compute some SHA1 keys.
|
|
||||||
|
|
||||||
- You need the "git" and "curl" packages to checkout the code.
|
|
||||||
If you plan to contribute, you might want to get "gitk" also.
|
|
||||||
|
|
||||||
Note: if you want to build the SDK, check the howto_build_SDK.txt file
|
|
||||||
for a list of extra required packages.
|
|
||||||
The short summary is that you need at least these:
|
|
||||||
autoconf, bison, curl, flex, gcc, g++, git, gnupg, make, mingw-zlib, python, unzip, zip
|
|
||||||
and you must avoid the "readline" package.
|
|
||||||
|
|
||||||
|
|
||||||
-----------------------------------
|
|
||||||
2- Getting the code, the simple way
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
Out of the box, "repo" and "git" will work just fine under Cygwin:
|
|
||||||
|
|
||||||
$ repo init -u git://android.git.kernel.org/platform/manifest.git
|
|
||||||
$ repo sync
|
|
||||||
|
|
||||||
And you're done. You can build as explained in howto_build_SDK.txt and ignore
|
|
||||||
the rest of this document.
|
|
||||||
|
|
||||||
|
|
||||||
-------------
|
|
||||||
3- SSH issues
|
|
||||||
-------------
|
|
||||||
|
|
||||||
If you maintain your own private repository using an SSH server, you might get
|
|
||||||
some "mux/ssh" errors. In this case try this:
|
|
||||||
|
|
||||||
$ repo init -u ssh://my.private.ssh.repo/platform/manifest.git
|
|
||||||
$ export GIT_SSH=ssh
|
|
||||||
$ repo sync
|
|
||||||
|
|
||||||
|
|
||||||
------------------
|
|
||||||
4- Advanced Tricks
|
|
||||||
------------------
|
|
||||||
|
|
||||||
There is one remaining issue with the default repo/git options:
|
|
||||||
|
|
||||||
If you plan on contributing, you will notice that even after a fresh "repo
|
|
||||||
sync" some projects are marked as having modified files. This happens on the
|
|
||||||
"bionic" and the "external/iptables" project. The issue is that they have files
|
|
||||||
which have the same name yet differ only by their case-sensitivity. Since the
|
|
||||||
Windows filesystem is not case-sensitive, this confuses Git.
|
|
||||||
|
|
||||||
Solution: we can simply ignore these projects as they are not needed to build
|
|
||||||
the Windows SDK.
|
|
||||||
|
|
||||||
To do this you just need to create a file .repo/local_manifest.xml that
|
|
||||||
provides a list of projects to ignore:
|
|
||||||
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<manifest>
|
|
||||||
<remove-project name="platform/external/iptables" />
|
|
||||||
</manifest>
|
|
||||||
|
|
||||||
The other thing we can do is tell git not to track the files that cause
|
|
||||||
problems:
|
|
||||||
|
|
||||||
cd bionic
|
|
||||||
git update-index --assume-unchanged \
|
|
||||||
libc/kernel/common/linux/netfilter/xt_CONNMARK.h \
|
|
||||||
libc/kernel/common/linux/netfilter/xt_MARK.h \
|
|
||||||
libc/kernel/common/linux/netfilter_ipv6/ip6t_HL.h
|
|
||||||
|
|
||||||
cd external/tcpdump;
|
|
||||||
git update-index --assume-unchanged \
|
|
||||||
tests/print-X.new \
|
|
||||||
tests/print-XX.new
|
|
||||||
|
|
||||||
|
|
||||||
Here's a script that takes care of all these details. It performs the repo
|
|
||||||
init, creates the appropriate local_manifest.xml, does a repo sync as
|
|
||||||
needed and tell git to ignore the offending files:
|
|
||||||
|
|
||||||
------------
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
set -e # fail on errors
|
|
||||||
|
|
||||||
URL=ssh://android-git.corp.google.com:29418/platform/manifest.git
|
|
||||||
BRANCH=donut
|
|
||||||
if [ "$1" == "-b" ]; then shift; BRANCH=$1; shift; fi
|
|
||||||
|
|
||||||
# repo init if there's no .repo directory
|
|
||||||
if [[ ! -d .repo ]]; then
|
|
||||||
repo init -u $URL -b $BRANCH
|
|
||||||
fi
|
|
||||||
|
|
||||||
# create a local_manifest to exclude projects that cause problems under Windows
|
|
||||||
# due to the case-insenstivines of the file system.
|
|
||||||
L=.repo/local_manifest.xml
|
|
||||||
if [[ ! -f $L ]]; then
|
|
||||||
|
|
||||||
cat > $L <<EOF
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<manifest>
|
|
||||||
<remove-project name="platform/external/iptables" />
|
|
||||||
</manifest>
|
|
||||||
EOF
|
|
||||||
fi
|
|
||||||
|
|
||||||
# sync using the native ssh client if necessary
|
|
||||||
[[ $URL != ${URL/ssh/} ]] && export GIT_SSH=ssh
|
|
||||||
repo sync $@
|
|
||||||
|
|
||||||
|
|
||||||
# These files cause trouble too, we need to ignore them
|
|
||||||
(cd bionic;
|
|
||||||
git update-index --assume-unchanged \
|
|
||||||
libc/kernel/common/linux/netfilter/xt_CONNMARK.h \
|
|
||||||
libc/kernel/common/linux/netfilter/xt_MARK.h \
|
|
||||||
libc/kernel/common/linux/netfilter_ipv6/ip6t_HL.h
|
|
||||||
)
|
|
||||||
(cd external/tcpdump;
|
|
||||||
git update-index --assume-unchanged \
|
|
||||||
tests/print-X.new \
|
|
||||||
tests/print-XX.new
|
|
||||||
)
|
|
||||||
------------
|
|
||||||
|
|
||||||
Simply extract this to a "my_sync.sh" file and try the following:
|
|
||||||
$ mkdir android_src
|
|
||||||
$ cd android_src
|
|
||||||
$ chmod +x mysync.sh
|
|
||||||
$ ./mysync.sh
|
|
||||||
|
|
||||||
|
|
||||||
-end-
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@@ -1,305 +0,0 @@
|
|||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
Subject: How to build an Android SDK & ADT Eclipse plugin.
|
|
||||||
Date: 2009/03/27
|
|
||||||
Updated: 2010/03/30
|
|
||||||
|
|
||||||
|
|
||||||
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
|
|
||||||
$ lunch sdk-eng
|
|
||||||
$ 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
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
You must have Cygwin installed. But wait! You CANNOT use the latest Cygwin 1.7.
|
|
||||||
Instead you MUST use the "legacy Cygwin 1.5" that you can find at this page:
|
|
||||||
|
|
||||||
http://cygwin.org/win-9x.html
|
|
||||||
|
|
||||||
Don't mind the page title, just grab setup-legacy.exe and it will works just fine
|
|
||||||
under XP or Vista.
|
|
||||||
|
|
||||||
|
|
||||||
Now configure it:
|
|
||||||
- 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-
|
|
||||||
|
|
||||||
@@ -1,371 +0,0 @@
|
|||||||
Subject: How to build use a Cupcake Android SDK & ADT Eclipse plugin.
|
|
||||||
Date: 2009/03/27
|
|
||||||
|
|
||||||
|
|
||||||
Table of content:
|
|
||||||
0- License
|
|
||||||
1- Foreword
|
|
||||||
2- Installation steps
|
|
||||||
3- For Eclipse users
|
|
||||||
4- For Ant users
|
|
||||||
5- Targets, AVDs, Emulator changes
|
|
||||||
6- 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 explains how to use the "new" SDK provided starting with cupcake.
|
|
||||||
The new SDK has as a different structure than the pre-cupcake ones.
|
|
||||||
|
|
||||||
This means:
|
|
||||||
- The new SDK does not work with older Eclipse plugins (ADT 0.8)
|
|
||||||
- The old SDKs (1.0 and 1.1) do NOT work with this Eclipse plugin (ADT 0.9)
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
----------------------
|
|
||||||
2- Installation steps
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
First you will need to grab the zip of the SDK for your platform or build it
|
|
||||||
yourself. Please refer to the accompanying document "howto_build_SDK.txt" if
|
|
||||||
needed.
|
|
||||||
|
|
||||||
Unzip the SDK somewhere. We'll call that directory "SDK" in command-line
|
|
||||||
examples.
|
|
||||||
|
|
||||||
Grab the new ADT Eclipse plugin zip file or build it yourself. Keep it
|
|
||||||
somewhere (no need to unzip).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
--------------------
|
|
||||||
3- For Eclipse users
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
|
|
||||||
Below we'll explain how you can upgrade your Eclipse install to the new plugin.
|
|
||||||
If you already have a working Eclipse installation with a pre-0.9 ADT,
|
|
||||||
another suggestion is to simply install a new copy of Eclipse and create a
|
|
||||||
new empty workspace. This is just a precaution. The update process should
|
|
||||||
be otherwise harmless.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
A- Setting up Eclipse
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
- You must have Eclipse 3.3 or 3.4. Eclipse 3.2 is not longer supported.
|
|
||||||
|
|
||||||
There are many flavors, or "editions", of Eclipse. To develop, we'd recommend
|
|
||||||
the "Java" edition. The "RCP" one is totally suitable too. The J2EE one is
|
|
||||||
probably overkill.
|
|
||||||
|
|
||||||
|
|
||||||
- If updating an existing Eclipse, use Help > Software Update and please
|
|
||||||
uninstall the two features of the previous ADT: the "editors" feature and the
|
|
||||||
ADT feature itself.
|
|
||||||
|
|
||||||
=> If you don't you will get a conflict on editors when installing
|
|
||||||
the new one.
|
|
||||||
|
|
||||||
- Using Help > Software Update, add a new "archived site", point it to the new
|
|
||||||
adt.zip (e.g. android-eclipse-<some-id>.zip), select the "Install" button at
|
|
||||||
the top right and restart eclipse as needed.
|
|
||||||
|
|
||||||
- After it restarts, please use Window > Preferences > Android and select
|
|
||||||
the new SDK folder that you unzipped in paragraph 2.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
B- Updating older projects
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
If you have pre-0.9 projects in your Eclipse workspace, or if you import them
|
|
||||||
from your code repository, these projects will fail to build at first.
|
|
||||||
|
|
||||||
First right-click on the project and select "Properties":
|
|
||||||
|
|
||||||
- In the properties, open the Android panel and select the platform to use.
|
|
||||||
The SDK comes with a 1.5 platform. Select it and close the properties panel.
|
|
||||||
- Do a clean build.
|
|
||||||
|
|
||||||
|
|
||||||
The new plugin creates a "gen" folder in your project where it puts the R.java
|
|
||||||
and all automatically generated AIDL java files. If you get an error such as:
|
|
||||||
|
|
||||||
"The type R is already defined"
|
|
||||||
|
|
||||||
that means you must check to see if your old R.java or your old auto-generated
|
|
||||||
AIDL Java files are still present in the "src" folder. If yes, remove them.
|
|
||||||
|
|
||||||
Note: this does not apply to your own hand-crafted parcelable AIDL java files.
|
|
||||||
|
|
||||||
Note: if you want to reuse the project with an older Eclipse ADT install,
|
|
||||||
simply remove the "gen" folder from the build path of the project.
|
|
||||||
|
|
||||||
|
|
||||||
C- New Wizards
|
|
||||||
--------------
|
|
||||||
|
|
||||||
The "New Android Project" wizard has been expanded to use the multi-platform
|
|
||||||
capabilities of the new SDK.
|
|
||||||
|
|
||||||
There is now a "New XML File" wizard that lets you create skeleton XML resource
|
|
||||||
files for your Android projects. This makes it easier to create a new layout, a
|
|
||||||
new strings file, etc.
|
|
||||||
|
|
||||||
Both wizard are available via File > New... as well as new icons in the main
|
|
||||||
icon bar. If you do not see the new icons, you may need to use Window > Reset
|
|
||||||
Perspective on your Java perspective.
|
|
||||||
|
|
||||||
|
|
||||||
Please see step 5 "Emulator changes" below for important details on how to run
|
|
||||||
the emulator.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
----------------
|
|
||||||
4- For Ant users
|
|
||||||
----------------
|
|
||||||
|
|
||||||
|
|
||||||
A- build.xml has changed
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
You must re-create your build.xml file.
|
|
||||||
|
|
||||||
First if you had customized your build.xml, make a copy of it:
|
|
||||||
|
|
||||||
$ cd my-project
|
|
||||||
$ cp build.xml build.xml.old
|
|
||||||
|
|
||||||
|
|
||||||
Then use the new "android" tool to create a new build.xml:
|
|
||||||
|
|
||||||
$ SDK/tools/android update project --path /path/to/my-project
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
$ cd my-project
|
|
||||||
$ SDK/tools/android update project --path .
|
|
||||||
|
|
||||||
|
|
||||||
A "gen" folder will be created the first time you build and your R.java and
|
|
||||||
your AIDL Java files will be generated in this "gen" folder. You MUST remove
|
|
||||||
the old R.java and old auto-generated AIDL java files manually. (Note: this
|
|
||||||
does not apply to your own hand-crafted parcelabe AIDL java files.)
|
|
||||||
|
|
||||||
|
|
||||||
B- Where is activitycreator?
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Note that the "activitycreator" tool has been replaced by the new "android"
|
|
||||||
tool too. Example of how to create a new Ant project:
|
|
||||||
|
|
||||||
$ SDK/tools/android create project --path /path/to/my/project --name ProjectName
|
|
||||||
--package com.mycompany.myapp --activity MyActivityClass
|
|
||||||
--target 1 --mode activity
|
|
||||||
|
|
||||||
|
|
||||||
Please see paragraph 5 below for important details on how to run the emulator
|
|
||||||
and the meaning of that "--target 1" parameter.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
----------------------------------
|
|
||||||
5- Targets, AVDs, Emulator changes
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
This applies to BOTH Eclipse and Ant users.
|
|
||||||
|
|
||||||
One major change with the emulator is that now you must pre-create an "Android
|
|
||||||
Virtual Device" (a.k.a "AVD") before you run the emulator.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
A- What is an AVD and why do I need one?
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
What is an "AVD"? If you forget, just run:
|
|
||||||
|
|
||||||
$ SDK/tools/emulator -help-virtual-device
|
|
||||||
|
|
||||||
An Android Virtual Device (AVD) models a single virtual device running the
|
|
||||||
Android platform that has, at least, its own kernel, system image and data
|
|
||||||
partition.
|
|
||||||
|
|
||||||
There is a lot more explanation given by the emulator. Please run the help
|
|
||||||
command given above to read the rest.
|
|
||||||
|
|
||||||
The bottom line is that you can create many emulator configurations, or "AVDs",
|
|
||||||
each with their own system image and most important each with their own user
|
|
||||||
data and SD card data. Then you tell Eclipse or the emulator which one to use
|
|
||||||
to debug or run your applications.
|
|
||||||
|
|
||||||
|
|
||||||
Note for Eclipse users: eventually there will be a user interface to do all of
|
|
||||||
these operations. For right now, please use the command line interface.
|
|
||||||
|
|
||||||
|
|
||||||
B- Listing targets and AVDs
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
There is a new tool called "android" in the SDK that lets you know which
|
|
||||||
"target" and AVDs you can use.
|
|
||||||
|
|
||||||
A target is a specific version of Android that you can use. By default the SDK
|
|
||||||
comes with an "Android 1.5" target, codenamed "cupcake". In the future there
|
|
||||||
will be more versions of Android to use, e.g. "Android 2.0" or specific add-ons
|
|
||||||
provided by hardware manufacturers. When you want to run an emulator, you need
|
|
||||||
to specify a given flavor of Android: this is the "target".
|
|
||||||
|
|
||||||
|
|
||||||
To learn about available targets in your SDK, use this command:
|
|
||||||
|
|
||||||
$ SDK/tools/android list targets
|
|
||||||
|
|
||||||
This will give you an output such as:
|
|
||||||
|
|
||||||
Available Android targets:
|
|
||||||
[1] Android 1.5
|
|
||||||
API level: 3
|
|
||||||
Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
|
|
||||||
|
|
||||||
Note the "[1]". Later you will need to reference this as "--target 1" on the
|
|
||||||
command line.
|
|
||||||
|
|
||||||
|
|
||||||
Similarly you can list the available AVDs:
|
|
||||||
|
|
||||||
$ SDK/tools/android list avds
|
|
||||||
|
|
||||||
Which might output something as:
|
|
||||||
|
|
||||||
Available Android Virtual Devices:
|
|
||||||
Name: my_avd
|
|
||||||
Path: C:\Users\<username>\.android\avd\my_avd.avd
|
|
||||||
Target: Android 1.5 (API level 3)
|
|
||||||
Skin: 320x480
|
|
||||||
Sdcard: 16M
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
C- Creating an AVD
|
|
||||||
------------------
|
|
||||||
|
|
||||||
To create a configuration:
|
|
||||||
|
|
||||||
$ SDK/tools/android create avd --name my_avd_name --target 1
|
|
||||||
|
|
||||||
|
|
||||||
where "target 1" is the index of a target listed by "android list targets".
|
|
||||||
|
|
||||||
The AVD name is purely an identifier used to refer to the AVD later.
|
|
||||||
Since it is used as directory name, please avoid using shell or path specific
|
|
||||||
characters.
|
|
||||||
|
|
||||||
To learn the various options available when creating an AVD, simply type:
|
|
||||||
|
|
||||||
$ SDK/tools/android create avd
|
|
||||||
|
|
||||||
The android tool will automatically print an explanation of required arguments.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
D- Invoking an AVD from the command-line
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
To use this AVD in the emulator from the command-line, type:
|
|
||||||
|
|
||||||
$ SDK/tools/emulator @my_avd_name
|
|
||||||
|
|
||||||
|
|
||||||
For more options, please consult the emulator help:
|
|
||||||
|
|
||||||
$ SDK/tools/emulator -help-virtual-device
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
E- Invoking an AVD from Eclipse
|
|
||||||
-------------------------------
|
|
||||||
|
|
||||||
By default Android projects in Eclipse have an "automatic target" mode.
|
|
||||||
In this mode, when a project is deployed in debug or run, it checks:
|
|
||||||
- If there's one running device or emulator, this is used for deployment.
|
|
||||||
- If there's more than one running device or emulator, a "device chooser" is
|
|
||||||
shown to let the user select which one to use.
|
|
||||||
- If there are no running devices or emulators, ADT looks at available AVDs.
|
|
||||||
If one matches the project configuration (e.g. same API level), it is
|
|
||||||
automatically used.
|
|
||||||
|
|
||||||
Alternatively you can edit the "launch configuration" on your Android project
|
|
||||||
in Eclipse by selecting the menu Run > Run Configurations. In the "target" tab
|
|
||||||
of the configuration, you can choose:
|
|
||||||
|
|
||||||
- Manual or automatic targetting mode.
|
|
||||||
|
|
||||||
- Manual means to always present the device chooser.
|
|
||||||
- Automatic is the behavior explained above.
|
|
||||||
|
|
||||||
- In automatic mode, which AVD is preferred. If none is selected, the first
|
|
||||||
suitable is used.
|
|
||||||
|
|
||||||
|
|
||||||
F- AVD concurrency
|
|
||||||
------------------
|
|
||||||
|
|
||||||
You can no longer run several emulators at the same time on the same
|
|
||||||
configuration.
|
|
||||||
|
|
||||||
Before this used to put the second or more emulators in a transient read-only
|
|
||||||
mode that would not save user data.
|
|
||||||
|
|
||||||
Now you just need to create as many AVDs as you want to run emulators.
|
|
||||||
|
|
||||||
For example if you are working on a client/server application for Android, you
|
|
||||||
could create a "client" AVD and a "server" AVD then run them both at once. The
|
|
||||||
emulator window will show you the AVD name so that you know which one is which.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
$ SDK/tools/android create avd --name client --target 1 --sdcard 16M --skin HVGA
|
|
||||||
$ SDK/tools/android create avd --name server --target 1 --sdcard 32M --skin HVGA-P
|
|
||||||
$ SDK/tools/emulator @server &
|
|
||||||
$ SDK/tools/emulator @client &
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
-------------
|
|
||||||
6- Conclusion
|
|
||||||
-------------
|
|
||||||
|
|
||||||
This completes the howto guide on how to use the new Cupcake SDK.
|
|
||||||
Feedback is welcome on the public Android Open Source forums:
|
|
||||||
http://source.android.com/discuss
|
|
||||||
|
|
||||||
-end-
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user