Unless you know that you'll be using new APIs introduced in ...

fansbutterflyMobile - Wireless

Jul 19, 2012 (4 years and 9 months ago)

880 views

Unless you know that you'll be using new APIs introduced in the latest SDK, you should select a target with the
lowest platform version possible.
Note: You can change your the Build Target for your project at any time: Right-click the project in the
Package Explorer, select Properties, select Android and then check the desired Project Target.
Under Properties, fill in all necessary fields. ◦
Enter an Application name. This is the human-readable title for your application —
the name that will appear
on the Android device.

Enter a Package name. This is the package namespace (following the same rules as for packages in the
Java programming language) where all your source code will reside.

Select Create Activity (optional, of course, but common) and enter a name for your main Activity class.■
Enter a Min SDK Version. This is an integer that indicates the minimum API Level required to properly run
your application. Entering this here automatically sets the
minSdkVersion
attribute in the
<uses-sdk>
of
your Android Manifest file. If you're unsure of the appropriate
API Level
to use, copy the API Level listed for
the Build Target you selected in the Target tab.

Click Finish.4.
Tip: You can also start the New Project Wizard from the New icon in the toolbar.
Once you complete the New Project Wizard, ADT creates the following folders and files in your new project:
src/
Includes your stub Activity Java file. All other Java files for your application go here.
<Android Version>/
(e.g.,
Android 1.1/
)
Includes the
android.jar
file that your application will build against. This is determined by the build target that you
have chosen in the New Project Wizard.
gen/
This contains the Java files generated by ADT, such as your
R.java
file and interfaces created from AIDL files.
assets/
This is empty. You can use it to store raw asset files.
res/
A folder for your application resources, such as drawable files, layout files, string values, etc. See
Application
Resources
.
AndroidManifest.xml
The Android Manifest for your project. See
The AndroidManifest.xml File
.
default.properties
This file contains project settings, such as the build target. This files is integral to the project, as such, it should be
maintained in a Source Revision Control system. It should never be edited manually — to edit project p roperties,
right-click the project folder and select "Properties".
Creating an

AVD
An Android Virtual Device (AVD) is a device configuration for the emulator that allows you to model real world devices. In
order to run an instance of the emulator, you must create an AVD.
To create an AVD from Eclipse:
Page
2
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
Use the Emulator to Test Different Configurations
Create multiple AVDs that each define a different
device configuration with which your application is
compatible, then launch each AVD into a new
emulator from the SDK and AVD Manager. Set the
target mode in your app's run configuration to manual,
so that when you run your application, you can select
from the available virtual devices.
Select Window > Android SDK and AVD Manager, or click the Android SDK and AVD Manager icon in the Eclipse
toolbar.
1.
In the Virtual Devices panel, you'll see a list of existing AVDs. Click New to create a new AVD.2.
Fill in the details for the AVD. 3.
Give it a name, a platform target, an SD card size, and a skin (HVGA is default).
Note: Be sure to define a target for your AVD that satisfies your application's Build Target (the AVD platform
target must have an API Level equal to or greater than the API Level that your application compiles against).
Click Create AVD.4.
Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or launch an emulator
with the AVD by selecting a device and clicking Start.
For more information about AVDs, read the
Android Virtual Devices
documentation.
Running Your Application
Running your application from Eclipse will usually require just
a couple clicks, whether you're running it on the emulator or
on an attached device. The information below describes how
to get set up and run your application from Eclipse.
Running on the emulator
Before you can run your application on the Android Emulator,
you must
create an AVD
.
To run (or debug) your application, select Run > Run (or Run
> Debug) from the Eclipse menu bar. The ADT plugin will automatically create a default launch configuration for the
project. Eclipse will then perform the following:
Compile the project (if there have been changes since the last build).1.
Create a default launch configuration (if one does not already exist for the project).2.
Install and start the application on an emulator (or device), based on the Deployment Target defined by the run
configuration.
3.
By default, Android run configurations use an "automatic target" mode for selecting a device target. For information
on how automatic target mode selects a deployment target, see
Automatic and manual target modes
below.
If debugging, the application will start in the "Waiting For Debugger" mode. Once the debugger is attached, Eclipse will
open the Debug perspective.
To set or change the launch configuration used for your project, use the launch configuration manager. See
Creating a
Launch Configuration
for information.
Be certain to create multiple AVDs upon which to test your application. You should have one AVD for each platform and
screen type with which your application is compatible. For instance, if your application compiles against the Android 1.5
(API Level 3) platform, you should create an AVD for each platform equal to and greater than 1.5 and an AVD for each
screen type
you support, then test your application on each one.
Running on a device
Before you can run your application on a device, you must perform some basic setup for your device:
Page
3
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
Declare your application as debuggable in your manifest•
Enable USB Debugging on your device•
Ensure that your development computer can detect your device when connected via USB•
Read
Setting up a Device for Development
for more information.
Once set up and your device is connected via USB, install your application on the device by selecting Run > Run (or Run
> Debug) from the Eclipse menu bar.
Creating a Run Configuration
The run configuration specifies the project to run,
the Activity to start, the emulator or connected device to use, and so on.
When you first run a project as an Android Application, ADT will automatically create a run configuration. The default run
configuration will launch the default project Activity and use automatic target mode for device selection (with no preferred
AVD). If the default settings don't suit your project, you can customize the launch configuration or even create a new.
To create or modify a launch configuration, follow these steps as appropriate for your Eclipse version:
Open the run configuration manager. 1.
In Eclipse 3.3 (Europa), select Run > Open Run Dialog (or Open Debug Dialog) ◦
In Eclipse 3.4 (Ganymede), select Run > Run Configurations (or Debug Configurations) ◦
Expand the Android Application item and create a new configuration or open an existing one. 2.
To create a new configuration: ◦
Select Android Application and click the New launch configuration icon above the list (or, right-click
Android Application and click New).
1.
Enter a Name for your configuration.2.
In the Android tab, browse and select the project you'd like to run with the configuration.3.
To open an existing configuration, select the configuration name from the list nested below Android
Application.

Adjust your desired launch configuration settings. 3.
In the Target tab, consider whether you'd like to use Manual or Automatic mode when selecting an AVD to run your
application. See the following section on
Automatic and manual target modes
).
You can specify any emulator options to the Additional Emulator Command Line Options field. For example, you
could add
-scale 96dpi
to scale the AVD's screen to an accurate size, based on the dpi of your computer
monitor.
For a full list of emulator options, see the
Android Emulator
document.
Automatic and manual

target modes
By default, a run configuration uses the automatic target mode in order to select an AVD. In this mode, ADT will select
an AVD for the application in the following manner:
If there's a device or emulator already running and its AVD configuration meets the requirements of the application's
build target, the application is installed and run upon it.
1.
If there's more than one device or emulator running, each of which meets the requirements of the build target, a
"device chooser" is shown to let you select which device to use.
2.
If there are no devices or emulators running that meet the
requirements of the build target, ADT looks at the available
AVDs. If one meets the requirements of the build target, the AVD is used to launch a new emulator, upon which the
application is installed and run.
3.
Page
4
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
Library project example code
The SDK includes an example application called
TicTacToeMain that shows how a dependent
application can use code and resources from an
Android Library project. The TicTacToeMain
application uses code and resources from an example
library project called TicTacToeLib.
To download the sample applications and run them as
projects in your environment, use the Android SDK
and AVD Manager to download the "Samples for SDK
API 8" component into your SDK.
For more information and to browse the code of the
samples, see the
TicTacToeMain application
.
If all else fails, the application will not be run and you will see a console error warning you that there is no existing
AVD that meets the build target requirements.
4.
However, if a "preferred AVD" is selected in the run configuration, then the application will always be deployed to that
AVD. If it's not already running, then a new emulator will be launched.
If your run configuration uses manual mode, then the "device chooser" is presented every time that your application is
run, so that you can select which AVD to use.
Signing your Applications
As you begin developing Android applications, understand that all Android
applications must be digitally signed before the
system will install them on an emulator or an actual device. There are two ways to do this: with a debug key (for
immediate testing on an emulator or development device) or with a private key (for application distribution).
The ADT plugin helps you get started quickly by signing your .apk files with a debug key, prior to installing them on an
emulator or development device. This means that you can quickly run your application from Eclipse without having to
generate your own private key. No specific action on your part is needed, provided ADT has access to Keytool.However,
please note that if you intend to publish your application, you must sign the application with your own private key, rather
than the debug key generated by the SDK tools.
Please read
Signing Your Applications
, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer. The document also includes a guide to exporting and signing your
application with the ADT's Export Wizard.
Working with Library Projects
An Android library project is a development project that holds
shared Android source code and resources. Other Android
application projects can reference the library project and, at
build time, include its compiled sources in their
.apk
files.
Multiple application projects can reference the same library
project and any single application project can reference
multiple library projects.
If you have source code and resources that are common to
multiple application projects, you can move them to a library
project so that it is easier to maintain across applications and
versions. Here are some common scenarios in which you
could make use of library projects:
If you are developing multiple related applications that
use some of the same components, you move the
redundant components out of their respective application
projects and create a single, reuseable set of the same components in a library project.

If you are creating an application that exists in both free and paid versions. You move the part of the application that
is common to both versions into a library project. The two dependent projects, with their different package
names, will
reference the library project and provide only the difference between the two application versions.

Structurally, a library project is similar to a standard Android application project. For example, it includes a manifest file at
the project root, as well as
src/
,
res/
and similar directories. The project can contain the same types of source code
Page
5
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
and resources as a standard Android project, stored in the same way. For example, source code in the library project can
access its own resources through its
R
class.
However, a library project differs from an standard Android application project in that you cannot compile it directly to its
own
.apk
or run it on the Android platform. Similarly, you cannot export the library project to a self-contained JAR file, as
you would do for a true library. Instead, you must compile the library indirectly, by referencing the library from a
dependent application's build path, then building that application.
When you build an application that depends on a library project, the SDK tools compile the library and merge its sources
with those in the main project, then use the result to generate the
.apk
. In cases where a resource ID is defined in both
the application and the library, the tools ensure that the resource declared in the application gets priority and that the
resource in the library project is not compiled into the application
.apk
. This gives your application the flexibility to either
use or redefine any resource behaviors or values that are defined in any library.
To organize your code further, your application can add references to multiple library projects, then specify the relative
priority of the resources in each library. This lets you build up the resources actually used in your application in a
cumulative manner. When two libraries referenced from an application define the same resource ID, the tools select the
resource from the library with higher priority and discard the other.
ADT lets you add references to library projects and set their relative priority from the application project's Properties. As
shown in Figure 2, below, once you've added a reference to a library project, you can use the Up and Down controls to
change the ordering, with the library listed at the top getting the higher priority. At build time, the libraries are merged with
the application one at a time, starting from the lowest priority to the highest.
Note that a library project cannot itself reference another library project and that, at build time, library projects are not
merged with each other before being merged with the application. However, note that a library can import an external
library (JAR) in the normal way.
The sections below describe how to use ADT to set up and manage library your projects. Once you've set up your library
projects and moved code into them, you can import library classes and resources to your application in the normal way.
Development requirements
Android library projects are a build-time construct, so you can use them to build a final application
.apk
that targets any
API level and is compiled against any version of the Android library.
However, to use library projects, you need to update your development environment to use the latest tools and platforms,
since older releases of the tools and platforms do not support building with library projects. Specifically, you need to
download and install the versions listed below:
Table 1. Minimum versions of SDK tools and plaforms on which you can develop library projects.
Component Minimum Version
SDK Tools r6 (or higher)
Android 2.2 platform r1 (or higher)
Android 2.1 platform r2 (or higher)
Android 2.0.1 platform not supported
Android 2.0 platform not supported
Android 1.6 platform r3 (or higher)
Android 1.5 platform r4 (or higher)
ADT Plugin 0.9.7 (or higher)
Page
6
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
Creating the manifest file
A library project's manifest file must declare all of the shared components that it includes, just as would a standard
Android application. For more information, see the documentation for
AndroidManifest.xml
.
For example, the
TicTacToeLib
example library project declares the Activity
GameActivity
:
<manifest>

...

<application>

...

<activity

android:name
=
"GameActivity"

/>

...

</application>

...
</manifest>
Referencing a library project from an application
If you are developing an application and want to include the shared code or resources from a library project, you can do
so easily by adding a reference to the library project in the application project's Properties.
To add a reference to a library project, follow these steps:
In the Package Explorer, right-click the dependent project and select Properties.1.
In the Properties window, select the "Android" properties group at left and locate the Library properties at right.2.
Click Add to open the Project Selection dialog. 3.
From the list of available library projects, select a project and click OK.4.
When the dialog closes, click Apply in the Properties window.5.
Click OK to close the Properties window.6.
As soon as the Properties dialog closes, Eclipse rebuilds the project, including the contents of the library project.
The figure below shows the Properties dialog that lets you add library references and move them up and down in priority.
Page
8
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
...
</manifest>
For more information about the manifest file, see the documentation for
AndroidManifest.xml
.
Development considerations
As you develop your library project and dependent applications, keep the points listed below in mind.
Resource conflicts
Since the tools merge the resources of a library project with those of a dependent application project, a given resource ID
might be defined in both projects. In this case, the tools select the resource from the application, or the library with highest
priority, and discard the other resource. As you develop your applications, be aware that common resource IDs are likely
to be defined in more than one project and will be merged, with the resource from the application or highest-priority library
taking precedence.
Using prefixes to avoid resource conflicts
To avoid resource conflicts for common resource IDs, consider using a prefix or other consistent naming scheme that is
unique to the project (or is unique across all projects).
No export of library project to JAR
A library cannot be distributed as a binary file (such as a jar file). This is because the library project is compiled by the
main project to use the correct resource IDs.
One library project cannot reference another
A library cannot depend on another library.
A library project can include a JAR library
You can develop a library project that itself includes a JAR library, however you need to manually edit the dependent
application project's build path and add a path to the JAR file.
A library project can depend on an external JAR library
You can develop a library project that depends on an external library (for example, the Maps external library). In this case,
the dependent application must build against a target that includes the external library (for example, the Google APIs Add
-On). Note also that both the library project and the dependent application must declare the external library their manifest
files, in a
<uses-library>
element.
Library project can not include AIDL files
The tools do not support the use of
AIDL
files in a library project. Any AIDL files used by an application must be stored in
the application project itself.
Library project can not include raw assets
The tools do not support the use of raw asset files in a library project. Any asset resources used by an application must
be stored in the
assets/
directory of the application project itself.
Targeting different Android platform versions in library project and application project
A library is compiled as part of the dependent application project, so the API used in the library project must be
compatible with the version of the Android library used to compile the application project. In general, the library project
should use an
API level
that is the same as — or lower than — that used by the application. If the library project uses an
API level that is higher than that of the application, the application project will fail to compile. It is perfectly acceptable to
Page
10
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
have a library that uses the Android 1.5 API (API level 3) and that is used in an Android 1.6 (API level 4) or Android 2.1
(API level 7) project, for instance.
No restriction on library package name
There is no requirement for the package name of a library to be the same as that of applications that use it.
Multiple R classes in gen/ folder of application project
When you build the dependent application project, the code of any libraries is compiled and merged to the application
project. Each library has its own
R
class, named according to the library's package name. The
R
class generated from the
resources of the main project and of the library is created in all the packages that are needed including the main project’s
package and the libraries’ packages.
Testing a library project
There are two recommended ways of setting up testing on code and resources in a library project:
You can set up a
test project
that instruments an application project that depends on the library project. You can then
add tests to the project for library-specific features.

You can set up a set up a standard application project that depends on the library and put the instrumentation in that
project. This lets you create a self-contained project that contains both the tests/instrumentations and the code to
test.

Library project storage location
There are no specific requirements on where you should store a library project, relative to a dependent application
project, as long as the application project can reference the library project by a relative link. You can place the library
project What is important is that the main project can reference the library project through a relative link.
Eclipse Tips
Executing arbitrary Java expressions in Eclipse
You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, when in a function with a String
argument called "zip", you can get information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering
android.os.Debug.startMethodTracing()
will start dmTrace.
Open a code execution window, select Window > Show View > Display from the main menu to open the Display
window, a simple text editor. Type your expression, highlight the text, and click the 'J' icon (or CTRL + SHIFT + D) to run
your code. The code runs in the context of the selected thread, which must be stopped at a breakpoint or single-step
point. (If you suspend the thread manually, you have to single-step once; this doesn't work if the thread is in Object.wait
().)
If you are currently paused on a breakpoint, you can simply highlight and execute a piece of source code by pressing
CTRL + SHIFT + D.
You can highlight a block of text within the same scope by pressing ALT +SHIFT + UP ARROW to select larger and larger
enclosing blocks, or DOWN ARROW to select smaller blocks.
Here are a few sample inputs and responses in Eclipse using the Display window.
Page
11
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
↑ Go to top
Input Response
zip (java.lang.String) /work/device/out/linux-x86-
debug/android/app/android_sdk.zip
zip.endsWith
(".zip")
(boolean) true
zip.endsWith
(".jar")
(boolean) false
You can also execute arbitrary code when not debugging by using a scrapbook page. Search the Eclipse documentation
for "scrapbook".
Running DDMS Manually
Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure
Eclipse to
debug on port 8700. (Note: Be sure that you have first started
DDMS
).
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1
-

14 May 2010 15:20
Site Terms of Service
-
Privacy Policy
-
Brand Guidelines

Page
12
of
12
Developing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\eclipse
-
adt.html
Creating an Android Project
To create an Android project, you must use the
android
tool. When you create a new project with
android
, it will
generate a project directory with some default application files, stub files, configuration files and a build file.
Creating a new Project
If you're starting a new project, use the
android create project
command to generate all the necessary files and
folders.
To create a new Android project, open a command-line, navigate to the
tools/
directory of your SDK and run:
android create project \
--target <target_ID> \
--name <your_project_name> \
--path path/to/your/project \
--activity <your_activity_name> \
--package <your_package_namespace>
target
is the "build target" for your application. It corresponds to an Android platform library (including any add-ons,
such as Google APIs) that you would like to build your project against. To see a list of available targets and their
corresponding IDs, execute:
android list targets
.

name
is the name for your project. This is optional. If provided, this name will be used for your .apk filename when
you build your application.

path
is the location of your project directory. If the directory does not exist, it will be created for you.•
activity
is the name for your default
Activity
class. This class file will be created for you inside
<path_to_your_project>/src/<your_package_namespace_path>/
. This will also be used for your .apk
filename unless you provide a the
name
.

package
is the package namespace for your project, following the same rules as for packages in the Java
programming language.

Here's an example:
android create project \
--target 1 \
--name MyAndroidApp \
--path ./MyAndroidAppProject \
--activity MyAndroidAppActivity \
--package com.example.myandroid
The tool generates the following files and directories:
AndroidManifest.xml
- The application manifest file, synced to the specified Activity class for the project.•
build.xml
- Build file for Ant.•
default.properties
- Properties for the build system. Do not modify this file.•
build.properties
- Customizable properties for the build system. You can edit this file to override default build
settings used by Ant and provide a pointer to your keystore and key alias so that the build tools can sign your
application when built in release mode.

src/your/package/namespace/ActivityName.java
- The Activity class you specified during project creation.•
bin/
- Output directory for the build script.•
gen/
- Holds
Ant
-generated files, such as
R.java
. •
Page
2
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
libs/
- Holds private libraries.•
res/
- Holds project resources.•
src/
- Holds source code.•
tests/
- Holds a duplicate of all-of-the-above, for testing purposes.•
Once you've created your project, you're ready to begin development. You can move your project folder wherever you
want for development, but keep in mind that you must use the
Android Debug Bridge
(adb) — located in the SDK
tools/

directory — to send your application to the emulato r (discussed later). So you need access between your project solution
and the
tools/
folder.
Caution: You should refrain from moving the location of the SDK directory, because this will break the build scripts.
(They will need to be manually updated to reflect the new SDK location before they will work again.)
Updating a project
If you're upgrading a project from an older version of the Android SDK or want to create a new project from existing code,
use the
android update project
command to update the project to the new development environment. You can also
use this command to revise the build target of an existing project (with the
--target
option) and the project name (with
the
--name
option). The
android
tool will generate any files and folders (listed in the previous section) that are either
missing or need to be updated, as needed for the Android project.
To update an existing Android project, open a command-line and navigate to the
tools/
directory of your SDK. Now run:
android update project --name <project_name> --target <target_ID>
--path <path_to_your_project>
target
is the "build target" for your application. It corresponds to an Android platform library (including any add-ons,
such as Google APIs) that you would like to build your project against. To see a list of available targets and their
corresponding IDs, execute:
android list targets
.

path
is the location of your project directory.•
name
is the name for the project. This is optional—if y ou're not changing the project name, you don't need this.•
Here's an example:
android update project --name MyApp --target 2 --path ./MyAppProject
Preparing to Sign Your Application
As you begin developing Android applications, understand that all Android applications must
be digitally signed before the
system will install them on an emulator or device. There are two ways to do this: with a debug key (for immediate testing
on an emulator or development device) or with a private key (for application distribution).
The Android build tools help you get started by automatically signing your .apk files with a debug key at build time. This
means that you can compile your application and install it on the emulator without having to generate your own private
key. However, please note that if you intend to publish your application, you must sign the application with your own
private key, rather than the debug key generated by the SDK tools.
Please read
Signing Your Applications
, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer.
Page
3
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Building Your Application
There are two ways to build your application: one for testing/debugging your application — debug mode — and one for
building your final package for release — release mode. As described in the previous section, your application must be
signed before it can be installed on an emulator or device.
Whether you're building in debug mode or release mode, you need to use the Ant tool to compile and build your project.
This will create the .apk file that is installed onto the emulator or device. When you build in debug mode, the .apk file is
automatically signed by the SDK tools with a debug key, so it's instantly ready for installation (but only onto an emulator
or attached development device). When you build in release mode, the .apk file is unsigned, so you must manually sign it
with your own private key,
using Keytool and Jarsigner.
It's important that you read and understand
Signing Your Applications
, particularly once you're ready to release your
application and share it with end-users. That document describes the procedure for generating a private key and then
using it to sign your .apk file. If you're just getting started, however, you can quickly run your applications on an emulator
or your own development device by building in debug mode.
If you don't have Ant, you can obtain it from the
Apache Ant home page
. Install it and make sure it is in your executable
PATH. Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the
JDK is installed.
Note: When installing JDK on Windows, the default is to install in the "Program Files" directory. This location will
cause
ant
to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this:
set JAVA_HOME=c:\Progra~1\Java\<jdkdir>
. The easiest solution, however, is to install JDK in a non-
space directory, for example:
c:\java\jdk1.6.0_02
.
Building in debug

mode
For immediate application testing and debugging, you can build your application in debug mode and immediately install it
on an emulator. In debug mode, the build tools automatically sign your application with a debug key and optimize the
package with
zipalign
. However, you can (and should) also test your application in release mode. Debug mode simply
allows you to run your application without manually signing the application.
To build in debug mode:
Open a command-line and navigate to the root of your project directory.1.
Use Ant to compile your project in debug mode: 2.
ant debug
This creates your debug .apk file inside the project
bin/
directory, named
<your_project_name>-debug.apk
.
The file is already signed with the debug key and has been aligned with
zipalign
.
Each time you change a source file or resource, you must run Ant again in order to package up the latest version of the
application.
To install and run your application on an emulator, see the following section about
Running Your Application
.
Building in release mode
When you're ready to release and distribute your application to end-users, you must build your application in release
mode. Once you have built in release mode, it's a good idea to perform additional testing and debugging with the
final .apk.
Before you start building your application in release mode, be aware that you must sign the resulting application package
with your private key, and
should then align it using the
zipalign
tool. There are two approaches to building in release
Page
4
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
mode: build an unsigned package in release mode and then manually sign and align the package, or allow the build script
to sign and align the package for you.
Build unsigned
If you build your application unsigned, then you will need to manually sign and align the package.
To build an unsigned .apk in release mode:
Open a command-line and navigate to the root of your project directory.1.
Use Ant to compile your project in release mode: 2.
ant release
This creates your Android application .apk file inside the project
bin/
directory, named
<your_project_name>-
unsigned.apk
.
Note: The .apk file is unsigned at this point and can't be installed until signed with your private key.
Once you have created the unsigned .apk, your next step is to sign the .apk with your private key and then align it with
zipalign
. To complete this procedure, read
Signing Your Applications
.
When your .apk has been signed and aligned, it's ready to be distributed to end-users.
Build signed and

aligned
If you would like, you can configure the Android build script to automatically sign and align your application package. To
do so, you must provide the path to your keystore and the name of your key alias in your project's
build.properties

file. With this information provided, the build script will prompt you for your keystore and alias password when you build in
release mode and produce your final application package, which will be ready for distribution.
Caution: Due to the way Ant handles input, the password that you enter during the build process will be visible. If
you are concerned about your keystore and
alias password being visible on screen, then you may prefer to perform
the application signing manually, via Jarsigner (or a similar tool). To instead perform the signing procedure
manually,
build unsigned
and then continue with
Signing Your Applications
.
To specify your keystore and alias, open the project
build.properties
file (found in the root of the project directory)
and add entries for
key.store
and
key.alias
. For example:
key.store=path/to/my.keystore
key.alias=mykeystore
Save your changes. Now you can build a signed .apk in release mode:
Open a command-line and navigate to the root of your project directory.1.
Use Ant to compile your project in release mode: 2.
ant release
When prompted, enter you keystore and alias passwords. 3.
Caution: As described above, your password will be visible on the screen.
This creates your Android application .apk file inside the project
bin/
directory, named
<your_project_name>-
release.apk
. This .apk file has been signed with the private key specified in
build.properties
and aligned with
zipalign
. It's ready for installation and distribution.
Page
5
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Use the Emulator to Test Different Configurations
Create multiple AVDs that each define a different
device configuration with which your application is
compatible, then launch each AVD into a new
emulator from the SDK and AVD Manager. Set the
target mode in your app's run configuration to manual,
so that when you run your application, you can select
from the available virtual devices.
Once built and signed in release mode
Once you have signed your application with a private key, you can install it on an emulator or device as discussed in the
following section about
Running Your Application
. You can also try installing it onto a device from a web server. Simply
upload the signed APK to a web site, then load the .apk URL in your Android web browser to download the application
and begin installation. (On your device, be sure you have enabled Settings > Applications > Unknown sources.)
Creating an

AVD
An Android Virtual Device (AVD) is a device configuration for the emulator that allows you to model real world devices. In
order to run an instance of the emulator, you must create an AVD.
To create an AVD using the SDK tools:
Navigate to your SDK's
tools/
directory and execute the
android
tool with no arguments: 1.
android
This will launch the SDK and AVD Manager GUI.
In the Virtual Devices panel, you'll see a list of existing AVDs. Click New to create a new AVD.2.
Fill in the details for the AVD. 3.
Give it a name, a platform target, an SD card size, and a skin (HVGA is default).
Note: Be sure to define a target for your AVD that satisfies your application's build target (the AVD platform
target must have an API Level equal to or greater than the API Level that your application compiles against).
Click Create AVD.4.
Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or launch an emulator with the
AVD by clicking Start.
For more information about AVDs, read the
Android Virtual Devices
documentation.
Running Your Application
Running your application on a virtual or real device takes just
a couple steps. Remember to first
build your application
.
Running on the emulator
Before you can run your application on the Android Emulator,
you must
create an AVD
.
To run your application:
Open the SDK and AVD Manager and launch a virtual
device
1.
From your SDK's
tools/
directory, execute the
android
tool with no arguments:
android
Page
6
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
In the Virtual Devices view, select an AVD and click Start.
Install your application 2.
From your SDK's
tools/
directory, install the
.apk
on the emulator:
adb install <path_to_your_bin>.apk
Your APK file (signed with either a release or debug key) is in your project
bin/
directory after you
build your
application
.
If there is more than one emulator running, you must specify the emulator upon which to install the application, by its
serial number, with the
-s
option. For example:
adb -s emulator-5554 install path/to/your/app.apk
To see a list of available device serial numbers, execute
adb devices
.
If you don't see your application on the emulator. Try closing the emulator and launching the virtual device again from the
SDK and AVD Manager. Sometimes when you install an Activity for the first time, it won't show up in the application
launcher or be accessible by other applications. This is because the package manager usually examines manifests
completely only on emulator startup.
Be certain to create multiple AVDs upon which to test your application. You should have one AVD for each platform and
screen type with which your application is compatible. For instance, if your application compiles against the Android 1.5
(API Level 3) platform, you should create an AVD for each platform equal to and greater than 1.5 and an AVD for each
screen type
you support, then test your application on each one.
Tip: If you have only one emulator running, you can build your application and install it on the emulator in one
simple step. Navigate to the root of your project directory and use Ant to compile the project with install mode:
ant
install
. This will build your application, sign it with the debug key, and install it on the currently running emulator.
Running on a device
Before you can run your application on a device, you must perform some basic setup for your device:
Declare your application as debuggable in your manifest•
Enable USB Debugging on your device•
Ensure that your development computer can detect your device when connected via USB•
Read
Setting up a Device for Development
for more information.
Once your device is set up and connected via USB, navigate to your SDK's
tools/
directory and install the
.apk
on the
device:
adb -d install path/to/your/app.apk
The
-d
flag specifies that you want to use the attached device (in case you also have an emulator running).
For more information on the tools used above, please see the following documents:
android Tool

Android Emulator

Android Debug Bridge
(ADB)

Page
7
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Library project example code
The SDK includes an example application called
TicTacToeMain that shows how a dependent
application can use code and resources from an
Android Library project. The TicTacToeMain
application uses code and resources from an example
library project called TicTacToeLib.
To download the sample applications and run them as
projects in your environment, use the Android SDK
and AVD Manager to download the "Samples for SDK
API 8" component into your SDK.
For more information and to browse the code of the
samples, see the
TicTacToeMain application
.
Working with Library Projects
An Android library project is a development project that holds
shared Android source code and resources. Other Android
application projects can reference the library project and, at
build time, include its compiled sources in their
.apk
files.
Multiple application projects can reference the same library
project and any single application project can reference
multiple library projects.
If you have source code and resources that are common to
multiple application projects, you can move them to a library
project so that it is easier to maintain across applications and
versions. Here are some common scenarios in which you
could make use of library projects:
If you are developing multiple related applications that
use some of the same components, you move the
redundant components out of their respective application
projects and create a single, reuseable set of the same components in a library project.

If you are creating an application that exists in both free and paid versions. You move the part of the application that
is common to both versions into a library project. The two dependent projects, with their different package
names, will
reference the library project and provide only the difference between the two application versions.

Structurally, a library project is similar to a standard Android application project. For example, it includes a manifest file at
the project root, as well as
src/
,
res/
and similar directories. The project can contain the same types of source code
and resources as a standard Android project, stored in the same way. For example, source code in the library project can
access its own resources through its
R
class.
However, a library project differs from an standard Android application project in that you cannot compile it directly to its
own
.apk
or run it on the Android platform. Similarly, you cannot export the library project to a self-contained JAR file, as
you would do for a true library. Instead, you must compile the library indirectly, by referencing the library from a
dependent application's build path, then building that application.
When you build an application that depends on a library project, the SDK tools compile the library and merge its sources
with those in the main project, then use the result to generate the

.apk
. In cases where a resource ID is defined in both
the application and the library, the tools ensure that the resource declared in the application gets priority and that the
resource in the library project is not compiled into the application
.apk
. This gives your application the flexibility to either
use or redefine any resource behaviors or values that are defined in any library.
To organize your code further, your application can add references to multiple library projects, then specify the relative
priority of the resources in each library. This lets you build up the resources actually used in your application in a
cumulative manner. When two libraries referenced from an application define the same resource ID, the tools select the
resource from the library with higher priority and discard the other.
Once you've have added references, the tools let you set their relative priority by editing the application project's build
properties. At build time, the tools merge the libraries with the application one at a time, starting from the lowest priority to
the highest.
Note that a library project cannot itself reference another library project and that, at build time, library projects are not
merged with each other before being merged with the application. However, note that a library can import an external
library (JAR) in the normal way.
The sections below describe how to use ADT to set up and manage library your projects. Once you've set up your library
projects and moved code into them, you can import library classes and resources to your application in the normal way.
Page
8
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Development requirements
Android library projects are a build-time construct, so you can use them to build a final application
.apk
that targets any
API level and is compiled against any version of the Android library.
However, to use library projects, you need to update your development environment to use the latest tools and platforms,
since older releases of the tools and platforms do not support building with library projects. Specifically, you need to
download and install the versions listed below:
Table 1. Minimum versions of SDK tools and plaforms on which you can develop library projects.
Component Minimum Version
SDK Tools r6 (or higher)
Android 2.2 platform r1 (or higher)
Android 2.1 platform r2 (or higher)
Android 2.0.1 platform not supported
Android 2.0 platform not supported
Android 1.6 platform r3 (or higher)
Android 1.5 platform r4 (or higher)
ADT Plugin 0.9.7 (or higher)
You can download the tools and platforms using the Android SDK and AVD Manager, as described in
Adding SDK
Components
.
Setting up a new library project
A library project is a standard Android project, so you can create a new one in the same way as you would a new
application project. Specifically, you can use the
android
tool to generate a new library project with all of the necessary
files and folders.
Creating a library project
To create a new library project, navigate to the
<sdk>/tools/
directory and use this command:
android create lib-project --name
<your_project_name>
\
--target <target_ID> \
--path path/to/your/project \
--package <your_library_package_namespace>
The
create lib-project
command creates a standard project
structure that includes preset property that indicates to
the build system that the project is a library. It does this by adding this line to the project's
default.properties
file:
android.library=true
Once the command completes, the library project is created and you can begin moving
source code and resources into it,
as described in the sections below.
If you want to convert an existing application project to a library project, so that other applications can use it, you can do
so by adding a the
android.library=true
property to the application's
default.properties
file.
Page
9
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Creating the manifest file
A library project's manifest file must declare all of the shared components that it includes, just as would a standard
Android application. For more information, see the documentation for
AndroidManifest.xml
.
For example, the
TicTacToeLib
example library project declares the Activity
GameActivity
:
<manifest>
...
<application>
...
<activity android:name="GameActivity" />
...
</application>
...
</manifest>
Updating a library project
If you want to update the build properties (build target, location) of the library project, use this command:
android update lib-project \
--target <target_ID> \
--path path/to/your/project
Referencing a library project from an application
If you are developing an application and want to include the shared code or resources from a library project, you can do
so easily by adding a reference to the library project in the application project's build properties.
To add a reference to a library project, navigate to the
<sdk>/tools/
directory and use this command:
android update lib-project \
--target <target_ID> \
--path path/to/your/project
--library path/to/library_projectA
This command updates the application project's build properties to
include a reference to the library project. Specifically, it
adds an
android.library.reference.n
property to the project's
default.properties
file. For example:
android.library.reference.1=path/to/library_projectA
If you are adding references to multiple libraries, note that you can set their relative priority (and merge order) by
manually editing the
default.properties
file and adjusting the each reference's
.n
index as appropriate. For
example, assume these references:
android.library.reference.1=path/to/library_projectA
android.library.reference.2=path/to/library_projectB
android.library.reference.3=path/to/library_projectC
You can reorder the references to give highest priority to
library_projectC
in this way:
android.library.reference.2=path/to/library_projectA
android.library.reference.3=path/to/library_projectB
android.library.reference.1=path/to/library_projectC
Page
10
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
Note that the
.n
index in the references must begin at "1" and increase uniformly without "holes". References appearing
in the index after a hole are ignored.
At build time, the libraries are merged with the application one at a time, starting from the lowest priority to the highest.
Note that a library cannot itself reference another library and that, at build time, libraries are not merged with each other
before being merged with the application.
Declaring library components in the the manifest

file
In the manifest file of the application project, you must add
declarations of all components that the application will use that
are imported from a library project. For example, you must declare any
<activity>
,
<service>
,
<receiver>
,
<provider>
, and so on, as well as
<permission>
,
<uses-library>
, and similar elements.
Declarations should reference the library components by their fully-qualified package names, where appropriate.
For example, the
TicTacToeMain
example application declares the library Activity
GameActivity
like this:
<manifest>
...
<application>
...
<activity android:name="com.example.android.tictactoe.library.GameActivity" />
...
</application>
...
</manifest>
For more information about the manifest file, see the documentation for
AndroidManifest.xml
.
Building a dependent application
To build an application project that depends on one or more library projects, you can use the standard Ant build
commands and compile modes, as described in
Building Your Application
, earlier in this document. The
tools compile and
merge all libraries referenced by the application as part of compiling the dependent application project. No additional
commands or steps are necessary.
Development considerations
As you develop your library project and dependent applications, keep the points listed below in mind.
Resource conflicts
Since the tools merge the resources of a library project with those of a dependent application project, a given resource ID
might be defined in both projects. In this case, the tools select the resource from the application, or the library with highest

priority, and discard the other resource. As you develop your applications, be aware that common resource IDs are likely
to be defined in more than one project and will be merged, with the resource from the application or highest-priority
library
taking precedence.
Using prefixes to avoid resource conflicts
To avoid resource conflicts for common resource IDs, consider using a prefix or other consistent naming scheme that is
unique to the project (or is unique across all projects).
No export of library project to JAR
A library cannot be distributed as a binary file (such as a jar file). This is because the library project is compiled by the
main project to use the correct resource IDs.
One library project cannot reference another
Page
11
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
A library cannot depend on another library.
A library project can include a JAR library
You can develop a library project that itself includes a JAR library. When you build the dependent application project, the
tools automatically locate and include the library in the application
.apk
.
A library project can depend on an external JAR library
You can develop a library project that depends on an external library (for example, the Maps external library). In this case,
the dependent application must build against a target that includes the external library (for example, the Google APIs Add
-On). Note also that both the library project and the dependent application must declare the external library their manifest
files, in a
<uses-library>
element.
Library project cannot include AIDL files
The tools do not support the use of
AIDL
files in a library project. Any AIDL files used by an application must be stored in
the application project itself.
Library project cannot include raw assets
The tools do not support the use of raw asset files in a library project. Any asset resources used by an application must
be stored in the
assets/
directory of the application project itself.
Targeting different Android platform versions in library project and application project
A library is compiled as part of the dependent application project, so the API used in the library project must be
compatible with the version of the Android library used to compile the application project. In general, the library project
should use an
API level
that is the same as — or lower than — that used by the application. If the library project uses an
API level that is higher than that of the application, the application project will fail to compile. It is perfectly acceptable to
have a library that uses the Android 1.5 API (API level 3) and that is used in an Android 1.6 (API level 4) or Android 2.1
(API level 7) project, for instance.
No restriction on library package name
There is no requirement for the package name of a library to be the same as that of applications that use it.
Multiple R classes in gen/ folder of application project
When you build the dependent application project, the code of any libraries is compiled and merged to the application
project. Each library has its own
R
class, named according to the library's package name. The
R
class generated from the
resources of the main project and of the library is created in all the packages that are needed including the main project’s
package and the libraries’ packages.
Testing a library project
There are two recommended ways of setting up testing on code and resources in a library project:
You can set up a
test project
that instruments an application project that depends on the library project. You can then
add tests to the project for library-specific features.

You can set up a set up a standard application project that depends on the library and put the instrumentation in that
project. This lets you create a self-contained project that contains both the tests/instrumentations and the code to
test.

Library project storage location
There are no specific requirements on where you should store a library project, relative to a dependent application
project, as long as the application project can reference the library project by a relative link. You can place the library
project What is important is that the main project can reference the library project through a relative link.
Page
12
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
↑ Go to top
Attaching a Debugger to Your Application
This section describes how to display debug information on the screen (such as CPU usage), as well as how to hook up
your IDE to debug running applications on the emulator.
Attaching a debugger is automated using the Eclipse plugin, but you can configure other IDEs to listen on a debugging
port to receive debugging information:
Start the
Dalvik Debug Monitor Server (DDMS)
tool, which acts as a port forwarding service between your IDE
and the emulator.
1.
Set optional debugging configurations on your emulator, such as blocking application startup for an Activity until
a debugger is attached. Note that many of these debugging options can be used without DDMS, such as displaying
CPU usage or screen refresh rate on the emulator.
2.
Configure your IDE to attach to port 8700 for debugging. Read about
Configuring Your IDE to Attach to the
Debugging Port
.
3.
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1 - 14 May 2010 15:20
Site Terms of Service
-
Privacy Policy
-
Brand Guidelines

Page
13
of
13
Developing In Other IDEs | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\other
-
ide.html
↑ Go to top
example rules files below show how to add an entry for a single vendor ID (the HTC vendor ID). In order to
support more devices, you will need additional lines of the same format that provide a different value for the
SYSFS{idVendor}
property. For other IDs, see the table of
USB Vendor IDs
, below.
Log in as root and create this file:
/etc/udev/rules.d/51-android.rules
. 1.
For Gusty/Hardy, edit the file to read:
SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"
For Dapper, edit the file to read:
SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"
Now execute:
chmod a+r /etc/udev/rules.d/51-android.rules

2.
You can verify that your device is connected by executing
adb devices
from your SDK
tools/
directory. If connected,
you'll see the device name listed as a "device."
If using Eclipse, run or debug as usual. You will be presented with a Device Chooser dialog that lists the available
emulator(s) and connected device(s). Select the device upon which you want to install and run the application.
If using the
Android Debug Bridge
(adb), you can issue commands with the
-d
flag to target your connected device.
USB Vendor IDs
This table provides a reference to the vendor IDs needed in order to add USB device support on Linux. The USB Vendor
ID is the value given to the
SYSFS{idVendor}
property in the rules file, as described in step 3, above.
Manufacturer USB Vendor ID
Acer
0502
Dell
413c
Foxconn
0489
Garmin-Asus
091E
HTC
0bb4
Huawei
12d1
Kyocera
0482
LG
1004
Motorola
22b8
Nvidia
0955
Pantech
10A9
Samsung
04e8
Sharp
04dd
Sony Ericsson
0fce
ZTE
19D2
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1 - 14 May 2010 15:20
Site Terms of Service
-
Privacy Policy
-
Brand Guidelines

Page
2
of
2
Developing on a Device | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\device.html
The ADT Plugin for Eclipse integrates a number of the Android development tools (ADB, DDMS, logcat output, and
other functionality), so that you won't work with them directly but will utilize them through the Eclipse IDE.
Developer Settings in the Dev Tools app
The Dev Tools application included in the emulator system image exposes several settings that provide useful
information such as CPU usage and frame rate. See
Debugging and Testing with Dev Tools
below.
Debugging and Testing with Dev Tools
With the Dev Tools application, you can enable a number of settings on your device that will make it easier to test and
debug your applications.
The Dev Tools application is installed by default on all system images included with the SDK, so you can use it with the
Android Emulator. If you'd like to install the Dev Tools application on a real development device, you can copy the
application from your emulator and then install it on your device using ADB. To copy the application from a running
emulator, execute:
adb
-
e pull
/
system
/
app
/
Development
.
apk
./
Development
.
apk
This copies the .apk file into the current directory. Then install it on your connected device with:
adb
-
d install
Development
.
apk
To get started, launch the Dev Tools application and select Development Settings. This will open the Development
Settings page with the following options (among others):
Debug app
Lets you select the application to debug. You do not need to set this to attach a debugger, but setting this value has
two effects:
It will prevent Android from throwing an error if you pause on a breakpoint for a long time while debugging.•
It will enable you to select the Wait for Debugger option to pause application startup until your debugger
attaches (described next).

Wait for debugger
Blocks the selected application from loading until a debugger attaches. This way you can set a breakpoint in
onCreate(), which is important to debug the startup process of an Activity. When you change this option, any
currently running instances of the selected application will be killed. In order to check this box, you must have
selected a debug application as described in the previous option. You can do the same thing by adding
waitForDebugger()
to your code.
Show screen updates
Flashes a momentary pink rectangle on any screen sections that are being redrawn. This is very useful for
discovering unnecessary screen drawing.
Immediately destroy activities
Tells the system to destroy an activity as soon as it is stopped (as if Android had to reclaim memory). This is very
useful for testing the
onSaveInstanceState(Bundle)
/
onCreate(android.os.Bundle)
code path, which
would otherwise be difficult to force. Choosing this option will probably reveal a number of problems in your
application due to not saving state.
Show CPU usage
Page
2
of
5
Debugging Tasks | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\debug
-
tasks.html
Displays CPU meters at the top of the screen, showing how much the CPU is being used. The top red bar shows
overall CPU usage, and the green bar underneath it shows the CPU time spent in compositing the screen.
Note: You
cannot turn this feature off once it is on, without restarting the emulator.
Show background
Displays a background pattern when no activity screens are visible. This typically does not happen, but can happen
during debugging.
These settings will be remembered across emulator restarts.
Debugging Web

Pages
If you're developing a web application for Android devices, you can debug your JavaScript in the Android Browser using
the Console APIs, which will output messages to logcat. If you're familiar debugging web pages with Firefox's FireBug or
WebKit's Web Inspector, then you're probably familiar with the Console APIs. The Android Browser (and the
WebChromeClient
) supports most of the same APIs.
When you call a function from the Console APIs (in the DOM's
window.console
object), you will see the output in
logcat as a warning. For example, if your web page executes the following JavaScript:
console.log("Hello World");
Then the logcat output from the Android Browser will look like this:
W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82
All Console messages from the Android Browser are tagged with the name "browser" on Android platforms running API
Level 7 or higher. On platforms running API Level 6 or lower, Browser messages are tagged with the name "WebCore".
The Android Browser also formats console messages with the log message preceded by "Console:" and then followed by
the address and line number where the message occurred. (The format for the address and line number will appear
different from the example above on platforms running API Level 6 or lower.)
The Android Browser (and
WebChromeClient
) does not implement all of the Console APIs provided by Firefox or other
WebKit-based browsers. Primarily, you need to depend on the basic text logging functions:
console.log(String)

console.info(String)

console.warn(String)

console.error(String)

Although the Android Browser may not fully implement other Console functions, they will not raise run-time errors, but
may not behave the same as they do on other desktop browsers.
If you've implemented a custom
WebView
in your
application, then in order to receive messages that are sent through the
Console APIs, you must provide a
WebChromeClient
that implements the
onConsoleMessage()
callback method.
For example, assuming that the
myWebView
field references the
WebView
in your application, you can log debug
messages like this:
myWebView
.
setWebChromeClient
(
new

WebChromeClient
()

{


public

void
onConsoleMessage
(
String
message
,

int
lineNumber
,

String
sourceID
)

{


Log
.
d
(
"MyApplication"
,
message
+

" -- From line "

+
lineNumber
+

" of "

+

sourceID
);

Page
3
of
5
Debugging Tasks | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\debug
-
tasks.html

}

});
The
onConsoleMessage()
method will be called each time one of the Console methods is called from within your
WebView
.
When the "Hello World" log is executed through your
WebView
, it will now look like this:
D/MyApplication ( 430): Hello World -- From line 82 of
http://www.example.com/hello.html
Note: The
onConsoleMessage()
callback method was added with API Level 7. If you are using a custom
WebView
on a platform running API Level 6 or lower, then your Console messages will automatically be sent to
logcat with the "WebCore" logging tag.
Top Debugging Tips
Dump the stack trace
To obtain a stack dump from emulator, you can log in with
adb shell
, use "ps" to find the process you want, and
then "kill -3 ". The stack trace appears in the log file.
Display useful info on the emulator screen
The device can display useful information such as CPU usage or highlights around redrawn areas. Turn these
features on and off in the developer settings window as described in
Setting debug and test configurations on the
emulator
.
Get system state information from the emulator (dumpstate)
You can access dumpstate information from the Dalvik Debug Monitor Service tool. See
dumpsys and dumpstate
on
the adb topic page.
Get application state information from the emulator (dumpsys)
You can access dumpsys information from the Dalvik Debug Monitor Service tool. See
dumpsys and dumpstate
on
the adb topic page.
Get wireless connectivity information
You can get information about wireless connectivity using the Dalvik Debug Monitor Service tool. From the Device
menu, select "Dump radio state".
Log trace data
You can log method calls and other tracing data in an activity by calling
startMethodTracing()
. See
Running the
Traceview Debugging Program
for details.
Log radio data
By default, radio information is not logged to the system (it is a lot of data). However, you can enable radio logging
using the following commands:
adb shell
logcat -b radio
Capture screenshots
The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select Device > Screen
capture.
Use debugging helper classes
Page
4
of
5
Debugging Tasks | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\debug
-
tasks.html
↑ Go to top
Android provides debug helper classes such as
util.Log
and
Debug
for your convenience.
Also see the
Troubleshooting
document for answers to some common developing and debugging issues.
Configuring Your IDE to Attach to the Debugging Port
DDMS will assign a specific debugging port to every virtual machine that it finds on the emulator. You must either attach
your IDE to that port (listed on the Info tab for that VM), or you can use a default port 8700 to connect to whatever
application is currently selected on the list of discovered virtual machines.
Your IDE should attach to your application running on the emulator, showing you its threads and allowing you to suspend
them, inspect their state, and set breakpoints. If you selected "Wait for debugger" in the Development settings panel the
application will run when Eclipse connects, so you will need to set any breakpoints you want before connecting.
Changing either the application being debugged or the "Wait for debugger" option causes the system to kill the selected
application if it is currently running. You can use this to kill your application if it is in a bad state by simply going to the
settings and toggling the checkbox.
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1 - 14 May 2010 15:20
Site Terms of Service
-
Privacy Policy
-
Brand Guidelines

Page
5
of
5
Debugging Tasks | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\debug
-
tasks.html
Running tests from the command line
If you've created your tests in Eclipse, you can still run
your tests and test suites by using command-line tools
included with the Android SDK. You may want to do
this, for example, if you have a large number of tests
to run, if you have a large test case, or if you want a
fine level of control over which tests are run at a
particular time.
In the Test Target panel, set An Existing Android Project, click Browse, then select your Android application from the
list. You now see that the wizard has completed the Test Target Package, Application Name, and Package Name
fields for you (the latter two are in the Properties panel).
4.
In the Build Target panel, select the Android SDK platform that you will use to test your application. Make this the
same as the build target of the application under test.
5.
Click Finish to complete the wizard. If Finish is disabled, look for error messages at the top of the wizard dialog, and
then fix any problems.
6.
Creating a Test Application
Once you have created a test project, you populate it with a test Android application. This application does not require an
Activity
, although you can define one if you wish. Although your test application can combine Activities, Android test
class extensions, JUnit extensions, or ordinary classes, you should extend one of the Android test classes or JUnit
classes, because these provide the best testing features.
Test applications do not have an Android GUI. Instead, when you run the application in Eclipse with ADT, its results
appear in the JUnit view. If you run your tests with
InstrumentationTestRunner
(or a related test runner), then it will
run all the methods in each class. You can modify this behavior by using the
TestSuite
class.
To create a test application, start with one of Android's test classes in the Java package
android.test
. These extend
the JUnit
TestCase
class. With a few exceptions, the Android test classes also provide instrumentation for testing.
For test classes that extend
TestCase
, you probably want to override the
setUp()
and
tearDown()
methods:
setUp()
: This method is invoked before any of the test methods in the class. Use it to set up the environment for the
test. You can use
setUp()
to instantiate a new
Intent
object with the action
ACTION_MAIN
. You can then use this
intent to start the Activity under test.

Note: If you override this method, call
super.setUp()
as the first statement in your code.
tearDown()
: This method is invoked after all the test methods in the class. Use it to do garbage collection and re-
setting before moving on to the next set of tests.

Note: If you override this method, you must call
super.tearDown()
as the last statement in your code.
Another useful convention is to add the method
testPreConditions()
to your test class. Use this method to test that
the application under test is initialized correctly. If this test fails, you know that that the initial conditions were in error.
When this happens, further test results are suspect, regardless of whether or not the tests succeeded.
The Resources tab contains an
Activity Testing
tutorial with more information about creating test classes and methods.
Running Tests
When you run a test application in Eclipse with ADT, the
output appears in an Eclipse view panel. You can run the
entire test application, one class, or one method of a class.
To do this, Eclipse runs the
adb
command for running a test
application, and displays the output, so there is no difference
between running tests inside Eclipse and running them from
the command line.
As with any other application, to run a test application in
Eclipse with ADT you must either attach a device to your
Page
2
of
4
Testing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\testing\testing_eclipse.html
To run tests created in Eclipse with ADT with
command-line tools, you must first install additional
files into the test project using the
android
tool's
"create test-project" option. To see how to do this,
read the section
Creating a test project
in the topic
Testing in Other IDEs
.
computer or use the Android emulator. If you use the
emulator, you must have an Android Virtual Device (AVD)
that uses the same target
To run a test in Eclipse, you have two choices:
Run a test just as you run an application, by selecting
Run As... > Android JUnit Test from the project's
context menu or from the main menu's Run item.
1.
Create an Eclipse run configuration for your test project. This is useful if you want multiple test suites, each
consisting of selected tests from the project. To run a test suite, you run the test configuration.
2.
Creating and running test configurations is described in the next section.
To create and run a test suite using a run configuration:
In the Package Explorer, select the test project, then from the main menu, select Run > Run Configurations.... The
Run Configurations dialog appears.
1.
In the left-hand pane, find the Android JUnit Test entry. In the right-hand pane,
click the Test tab. The Name: text box
shows the name of your project. The Test class: dropdown box shows one your project's classes test classes in your
project.
2.
To run one test class, click Run a single test, then enter your project name in the Project: text box and the class
name in the Test class: text box.
3.
To run all the test classes, click Run all tests in the selected project or package, then enter the project or package
name in the text box.
Now click the Target tab. 4.
Optional: If you are using the emulator, click Automatic, then in the Android Virtual Device (AVD) selection table,
select an existing AVD.

In the Emulator Launch Parameters pane, set the Android emulator flags you want to use. These are
documented in the topic
Emulator Startup Options
.

Click the Common tab. In the Save As pane, click Local to save this run configuration locally, or click Shared to save
it to another project.
5.
Optional: Add the configuration to the Run toolbar and the Favorites menu: in the Display in Favorites pane click the
checkbox next to Run.
6.
Optional: To add this configuration to the Debug menu and toolbar, click the checkbox next to Debug. 7.
To save your settings, click Close. 8.
Note: Although you can run the test immediately by clicking Run, you should save the test first and then run it by
selecting it from the Eclipse standard toolbar.
On the Eclipse standard toolbar, click the down arrow next to the green Run arrow. This displays a menu of saved
Run and Debug configurations.
9.
Select the test run configuration you just created. 10.
The progress of your test appears in the Console view. You should see the following messages, among others: 11.
Performing Android.test.InstrumentationTestRunner JUnit launch

The class name that proceeds "JUnit" depends on the Android instrumentation class you have chosen.

If you are using an emulator and you have not yet started it, then you will see the message: ◦
Automatic Target Mode: launching new emulator with compatible AVD avdname

(where avdname is the name of the AVD you are using.)
If you have not already installed your test application, then you will see the message: ◦
Page
3
of
4
Testing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\testing\testing_eclipse.html
↑ Go to top
Uploading testclass.apk onto device 'device-id'

where testclass is the name of your unit test class and device-id is the name and port for your test device or
emulator, followed by the message
Installing testclass.apk

Launching instrumentation Android.test.InstrumentationTestRunner on device device-
id
.
This indicates that Android's Instrumentation system is now testing your code. Again, the instrumentation class
name depends on the Android instrumentation class you have chosen.

Test run complete
.
When you see this, your unit tests have finished.

The test results appear in the JUnit view. This is divided into an upper summary pane, and a lower stack trace pane.
The upper pane contains test information. In the pane's header, you see the following information:
Total time elapsed for the test application (labeled Finished after x seconds). •
Number of runs (Runs:) - the number of tests in the entire test class. •
Number of errors (Errors:) - the number of program errors and exceptions encountered during the test run. •
Number of failures (Failures:) - the number of test failures encountered during the test run. This is the number of
assertion failures. A test can fail even if the program does not encounter an error.

A progress bar. The progress bar extends from left to right as the tests run. If all the tests succeed, the bar remains
green. If a test fails, the bar turns from green to red.

The body of the upper pane contains the details of the test run. For each test case class that was run, you see a line with
the class name. To look at the results for the individual test methods in that class, you click the left arrow to expand the
line. You now see a line for each test method in the class, and to its right the time it took to run. If you double-click the
method name, Eclipse opens the test class source in an editor view pane and moves the focus to the first line of the test
method.
The lower pane is for stack traces. If you highlight a failed test in the upper pane, the lower pane contains a stack trace
for the test. If a line corresponds to a point in your test code, you can double-click it to display the code in an editor view
pane, with the line highlighted. For a successful test, the lower pane is empty.
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 2.2 r1 - 14 May 2010 15:20
Site Terms of Service
-
Privacy Policy
-
Brand Guidelines

Page
4
of
4
Testing In Eclipse, with ADT | Android Developers
9/7/2010
file://V:\android
-
sdk
-
windows\docs\guide\developing\testing\testing_eclipse.html
This creates a new test project with the appropriate directories and build files. The directory structure and build file
contents are identical to those in a regular Android application project. They are described in detail in the topic
Developing In Other IDEs
.
The operation also creates an
AndroidManifest.xml
file with instrumentation information. When you run the test,
Android uses this information to load the application you are testing and control it with instrumentation.
For example, suppose you create the
Hello, World
tutorial application in the directory