372 lines
11 KiB
Plaintext
372 lines
11 KiB
Plaintext
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/community
|
|
|
|
-end-
|
|
|