tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
base/docs/html/guide/developing/debug-tasks.jd
+232
View File
@@ -0,0 +1,232 @@
page.title=Debugging Tasks
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#tools">Tools</a></li>
<li><a href="#additionaldebugging">Debug with Dev Tools</a></li>
<li><a href="#DebuggingWebPages">Debugging Web Pages</a></li>
<li><a href="#toptips">Top Debugging Tips</a></li>
<li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li>
</ol>
</div>
</div>
<p>This document offers some helpful guidance to debugging applications on Android.
<h2 id="tools">Tools</h2>
<p>The Android SDK includes a set of tools to help you debug and profile
your applications. Here are some tools that you'll use most often:</p>
<dl>
<dt><strong><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge
(ADB)</a></strong></dt>
<dd>Provides various device management capabilities, including
moving and syncing files to the emulator, forwarding ports, and running a UNIX
shell on the emulator.</dd>
<dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server
(DDMS)</a></strong></dt>
<dd>A graphical program that
supports port forwarding (so you can set up breakpoints in your code in your
IDE), screen captures on the emulator, thread and stack information,
and many other features. You can also run logcat to retrieve your Log messages.</dd>
</dd>
<dt><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a></strong></dt>
<dd>A graphical viewer that displays trace file data for method calls and times saved by
your application, which can help you profile the performance of your application.</dd>
<dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt>
<dd>Dumps a log of system
messages. The messages include a stack trace when the device throws an error,
as well as {@link android.util.Log} messages you've written from your application. To run
logcat, execute <code>adb logcat</code> from your Android SDK {@code platform-tools/}
directory or, from DDMS, select <strong>Device > Run
logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT plugin for
Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from
<strong>Window > Show View > Other > Android > Logcat</strong>.
<p>{@link android.util.Log} is a logging
class you can use to print out messages to the logcat. You can read messages
in real time if you run logcat on DDMS (covered next). Common logging methods include:
{@link android.util.Log#v(String,String)} (verbose), {@link
android.util.Log#d(String,String)} (debug), {@link android.util.Log#i(String,String)}
(information), {@link android.util.Log#w(String,String)} (warning) and {@link
android.util.Log#e(String,String)} (error). For example:</p>
<pre class="no-pretty-print">
Log.i("MyActivity", "MyClass.getView() &mdash; get item number " + position);
</pre>
<p>The logcat will then output something like:</p>
<pre class="no-pretty-print">
I/MyActivity( 1557): MyClass.getView() &mdash; get item number 1
</pre>
<p>Logcat is also the place to look when debugging a web page in the Android Browser app. See
<a href="#DebuggingWebPages">Debugging Web Pages</a> below.</p>
</dl>
<p>For more information about all the development tools provided with the Android SDK, see the <a
href="{@docRoot}guide/developing/tools/index.html">Tools</a> document.</p>
<p>In addition to the above tools, you may also find the following useful for debugging:
<dl>
<dt><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse ADT
plugin</strong></a></dt>
<dd>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.</dd>
<dt><strong>Developer Settings in the Dev Tools app</strong></dt>
<dd>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 <a
href="#additionaldebugging">Debugging and Testing with Dev Tools</a> below.</dd>
</dl>
<h2 id="additionaldebugging">Debugging and Testing with Dev Tools</h2>
<p>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.</p>
<p>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:
</p>
<pre>
adb -e pull /system/app/Development.apk ./Development.apk
</pre>
<p>This copies the .apk file into the current directory. Then install it on your connected device
with:</p>
<pre>
adb -d install Development.apk
</pre>
<p>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):</p>
<dl>
<dt><strong>Debug app</strong></dt>
<dd>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:
<ul>
<li>It will prevent Android from throwing an error if you pause on
a breakpoint for a long time while debugging.</li>
<li>It will enable you to select the <em>Wait for Debugger</em> option
to pause application startup until your debugger attaches (described
next). </li>
</ul>
</dd>
<dt><strong>Wait for debugger</strong></dt>
<dd>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
{@link android.os.Debug#waitForDebugger()} to your code.</dd>
<dt><strong>Show screen updates</strong></dt>
<dd>Flashes a momentary pink rectangle on any screen sections that are being
redrawn. This is very useful for discovering unnecessary screen drawing.</dd>
<dt><strong>Immediately destroy activities</strong></dt>
<dd>Tells the
system to destroy an activity as soon as it is stopped (as if Android had to
reclaim memory).&nbsp; This is very useful for testing the {@link android.app.Activity#onSaveInstanceState}
/ {@link android.app.Activity#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.</dd>
<dt><strong>Show CPU usage</strong></dt>
<dd>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. <em>Note: You cannot turn this feature off
once it is on, without restarting the emulator.</em> </dd>
<dt><strong>Show background</strong></dt>
<dd>Displays a background pattern
when no activity screens are visible. This typically does not happen, but
can happen during debugging.</dd>
</dl>
<p>These settings will be remembered across emulator restarts.</p>
<h2 id="DebuggingWebPages">Debugging Web Pages</h2>
<p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p>
<h2 id="toptips">Top Debugging Tips</h2>
<dl>
<dt><strong>Dump the stack trace</strong></dt>
<dd>To obtain a stack dump from emulator, you can log
in with <code>adb shell</code>, use &quot;ps&quot; to find the process you
want, and then &quot;kill -3 &quot;. The stack trace appears in the log file.
</dd>
<dt><strong>Display useful info on the emulator screen</strong></dt>
<dd>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 <a href="#additionaldebugging">Setting debug and test
configurations on the emulator</a>.
</dd>
<dt><strong>Get system state information from the emulator (dumpstate)</strong></dt>
<dd>You can access dumpstate information from the Dalvik Debug Monitor Service
tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and
dumpstate</a> on the adb topic page.</dd>
<dt><strong>Get application state information from the emulator (dumpsys)</strong></dt>
<dd>You can access dumpsys information from the Dalvik Debug Monitor Service
tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and
dumpstate</a> on the adb topic page.</dd>
<dt><strong>Get wireless connectivity information</strong></dt>
<dd>You can get information about wireless connectivity using the Dalvik Debug
Monitor Service tool. From the <strong>Device</strong> menu, select &quot;Dump
radio state&quot;.</dd>
<dt><strong>Log trace data</strong></dt>
<dd>You can log method calls and other tracing data in an activity by calling
{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a
href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging
Program</a> for details. </dd>
<dt><strong>Log radio data</strong></dt>
<dd>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:
<pre class="no-pretty-print">
adb shell
logcat -b radio
</pre>
</dd>
<dt><strong>Capture screenshots</strong></dt>
<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select
<strong>Device > Screen capture</strong>.</dd>
<dt><strong>Use debugging helper classes</strong></dt>
<dd>Android provides debug helper classes such as {@link android.util.Log
util.Log} and {@link android.os.Debug} for your convenience. </dd>
</dl>
<p>Also see the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document
for answers to some common developing and debugging issues.</p>
<h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2>
<p>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.</p>
<p>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 &quot;Wait for debugger&quot; in the Development settings panel
the application will run when Eclipse connects, so you will need to set any breakpoints
you want before connecting.</p>
<p>Changing either the application being debugged or the &quot;Wait for debugger&quot;
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.</p>
base/docs/html/guide/developing/device.jd
+175
View File
@@ -0,0 +1,175 @@
page.title=Developing on a Device
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#setting-up">Setting up a Device for Development</a>
<ol>
<li><a href="#VendorIds">USB Vendor IDs</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a></li>
<li><a href="{@docRoot}sdk/oem-usb.html">OEM USB Drivers</a></li>
<li><a
href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse, with ADT</a></li>
<li><a
href="{@docRoot}guide/developing/other-ide.html">Developing in other IDEs</a></li>
</ol>
</div>
</div>
<p>When building a mobile application, it's important that you always test your application on a
real device before releasing it to users. This page describes how to set up your development
environment and Android-powered device for testing and debugging on the device.</p>
<p>You can use any Android-powered device as an environment for running,
debugging, and testing your applications. The tools included in the SDK make it easy to install and
run your application on the device each time you compile. You can install your application on the
device <a
href="{@docRoot}guide/developing/eclipse-adt.html#RunningOnDevice">directly from
Eclipse</a> or <a href="{@docRoot}guide/developing/other-ide.html#RunningOnDevice">from the
command line</a>. If
you don't yet have a device, check with the service providers in your area to determine which
Android-powered devices are available.</p>
<p>If you want a SIM-unlocked phone, then you might consider either an Android Dev Phone or the
Google Nexus S. These are SIM-unlocked so that you can use them on any GSM network using a SIM
card. The Android Dev Phones also feature an unlocked bootloader so you can install custom system
images (great for developing and installing custom versions of the Android platform). To find a
a place you can purchase the Nexus S, visit <a
href="http://www.google.com/phone/detail/nexus-s">google.com/phone</a>. To purchase an Android
Dev Phone, see the <a href="http://market.android.com/publish">Android Market</a> site
(requires a developer account).</p>
<p class="note"><strong>Note:</strong> When developing on a device, keep in mind that you should
still use the <a
href="{@docRoot}guide/developing/tools/emulator.html">Android emulator</a> to test your application
on configurations that are not equivalent to those of your real device. Although the emulator
does not allow you to test every device feature (such as the accelerometer), it does
allow you to verify that your application functions properly on different versions of the Android
platform, in different screen sizes and orientations, and more.</p>
<h2 id="setting-up">Setting up a Device for Development</h2>
<p>With an Android-powered device, you can develop and debug your Android applications just as you
would on the emulator. Before you can start, there are just a few things to do:</p>
<ol>
<li>Declare your application as "debuggable" in your Android Manifest.
<p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest
(on the right side, set <b>Debuggable</b> to <em>true</em>). Otherwise, in the <code>AndroidManifest.xml</code>
file, add <code>android:debuggable="true"</code> to the <code>&lt;application></code> element.</p>
</li>
<li>Turn on "USB Debugging" on your device.
<p>On the device, go to the home screen, press <b>MENU</b>, select <b>Applications</b> > <b>Development</b>,
then enable <b>USB debugging</b>.</p>
</li>
<li>Setup your system to detect your device.
<ul>
<li>If you're developing on Windows, you need to install a USB driver
for adb. If you're using an Android Developer Phone (ADP), Nexus One, or Nexus S,
see the <a href="{@docRoot}sdk/win-usb.html">Google Windows USB
Driver</a>. Otherwise, you can find a link to the appropriate OEM driver in the
<a href="{@docRoot}sdk/oem-usb.html">OEM USB Drivers</a> document.</li>
<li>If you're developing on Mac OS X, it just works. Skip this step.</li>
<li>If you're developing on Ubuntu Linux, you need to add a rules file
that contains a USB configuration for each type of device you want to use for
development. Each device manufacturer uses a different vendor ID. The
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
<code>SYSFS{idVendor}</code> property. For other IDs, see the table of <a
href="#VendorIds">USB Vendor IDs</a>, below.
<ol>
<li>Log in as root and create this file:
<code>/etc/udev/rules.d/51-android.rules</code>.
<p>For Gusty/Hardy, edit the file to read:<br/>
<code>SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4",
MODE="0666"</code></p>
<p>For Dapper, edit the file to read:<br/>
<code>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4",
MODE="0666"</code></p>
</li>
<li>Now execute:<br/>
<code>chmod a+r /etc/udev/rules.d/51-android.rules</code>
</li>
</ol>
</li>
</ul>
</li>
</ol>
<p>You can verify that your device is connected by executing <code>adb devices</code> from your
SDK {@code platform-tools/} directory. If connected, you'll see the device name listed as a
"device."</p>
<p>If using Eclipse, run or debug as usual. You will be presented
with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s).
Select the device upon which you want to install and run the application.</p>
<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb),
you can issue commands with the <code>-d</code> flag to target your
connected device.</p>
<h3 id="VendorIds">USB Vendor IDs</h3>
<p>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
<code>SYSFS{idVendor}</code> property in the rules file, as described in step 3, above.</p>
<table>
<tr>
<th>Manufacturer</th><th>USB Vendor ID</th></tr>
<tr>
<td>Acer</td>
<td><code>0502</code></td></tr>
<tr>
<td>Dell</td>
<td><code>413c</code></td></tr>
<tr>
<td>Foxconn</td>
<td><code>0489</code></td></tr>
<tr>
<td>Garmin-Asus</td>
<td><code>091E</code></td></tr>
<tr>
<td>HTC</td>
<td><code>0bb4</code></td></tr>
<tr>
<td>Huawei</td>
<td><code>12d1</code></td></tr>
<tr>
<td>Kyocera</td>
<td><code>0482</code></td></tr>
<tr>
<td>LG</td>
<td><code>1004</code></td></tr>
<tr>
<td>Motorola</td>
<td><code>22b8</code></td></tr>
<tr>
<td>Nvidia</td>
<td><code>0955</code></td></tr>
<tr>
<td>Pantech</td>
<td><code>10A9</code></td></tr>
<tr>
<td>Samsung</td>
<td><code>04e8</code></td></tr>
<tr>
<td>Sharp</td>
<td><code>04dd</code></td></tr>
<tr>
<td>Sony Ericsson</td>
<td><code>0fce</code></td></tr>
<tr>
<td>ZTE</td>
<td><code>19D2</code></td></tr>
</table>
base/docs/html/guide/developing/eclipse-adt.jd
+860
View File
@@ -0,0 +1,860 @@
page.title=Developing In Eclipse, with ADT
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#CreatingAProject">Creating an Android Project</a></li>
<li><a href="#AVD">Creating an AVD</a></li>
<li><a href="#Running">Running Your Application</a>
<ol>
<li><a href="#RunningOnEmulator">Running on the emulator</a></li>
<li><a href="#RunningOnDevice">Running on a device</a></li>
</ol>
</li>
<li><a href="#RunConfig">Creating a Run Configuration</a></li>
<li><a href="#Signing">Setting Up Application Signing</a></li>
<li><a href="#libraryProject">Working with Library Projects</a>
<ol>
<li><a href="#libraryReqts">Development requirements</a></li>
<li><a href="#librarySetup">Setting up a library project</a></li>
<li><a href="#libraryReference">Referencing a library project</a></li>
<li><a href="#considerations">Development considerations</a></li>
<li><a href="#libraryMigrating">Migrating library projects to ADT 0.9.8</a></li>
</ol>
</li>
<li><a href="#Tips">Eclipse Tips</a></li>
</div>
</div>
<p>The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse
integrated development environment. It allows you to create and debug Android applications easier
and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android
applications:</p>
<ul>
<li>It gives you access to other Android development tools from inside the Eclipse IDE. For
example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage
port-forwarding, set breakpoints, and view thread and process information directly from
Eclipse.</li>
<li>It provides a New Project Wizard, which helps you quickly create and set up all of the
basic files you'll need for a new Android application.</li>
<li>It automates and simplifies the process of building your Android application.</li>
<li>It provides an Android code editor that helps you write valid XML for your Android
manifest and resource files.</li>
<li>It will even export your project into a signed APK, which can be distributed to users.</li>
</ul>
<p>To begin developing Android applications in the Eclipse IDE with ADT, you first need to
download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the
steps given in <a href="{@docRoot}sdk/eclipse-adt.html#installing">Installing
the ADT Plugin</a>.</p>
<p>If you are already developing applications using a version of ADT earlier than 0.9, make
sure to upgrade to the latest version before continuing. See the guide to
<a href="{@docRoot}sdk/eclipse-adt.html#updating">Updating Your ADT Plugin</a>.</p>
<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of
the ADT plugin. While most of the information covered also applies to previous
versions, if you are using an older version, you may want to consult this document from
the set of documentation included in your SDK package (instead of the online version).</p>
<h2 id="CreatingAProject">Creating an Android Project</h2>
<p>The ADT plugin provides a New Project Wizard that you can use to quickly create a new
Android project (or a project from existing code). To create a new project:</p>
<ol>
<li>Select <strong>File</strong> &gt; <strong>New</strong> &gt; <strong>Project</strong>.</li>
<li>Select <strong>Android</strong> &gt; <strong>Android Project</strong>, and click
<strong>Next</strong>.</li>
<li>Select the contents for the project:
<ul>
<li>Enter a <em>Project Name</em>. This will be the name of the folder where your
project is created.</li>
<li>Under Contents, select <strong>Create new project in workspace</strong>.
Select your project workspace location.</li>
<li>Under Target, select an Android target to be used as the project's Build Target.
The Build Target
specifies which Android platform you'd like your application built against.
<p>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.</p>
<p class="note"><strong>Note:</strong> You can change your the Build Target for your
project at any time: Right-click the project in the Package Explorer, select
<strong>Properties</strong>, select <strong>Android</strong> and then check
the desired Project Target.</p>
</li>
<li>Under Properties, fill in all necessary fields.
<ul>
<li>Enter an <em>Application name</em>. This is the human-readable title for your
application &mdash; the name that will appear on the Android device.</li>
<li>Enter a <em>Package name</em>. This is the package namespace (following the same rules
as for packages in the Java programming language) where all your source code
will reside.</li>
<li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
for your main Activity class.</li>
<li>Enter a <em>Min SDK Version</em>. This is an integer that indicates
the minimum API Level required to properly run your application.
Entering this here automatically sets the <code>minSdkVersion</code> attribute in the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
of your Android Manifest file. If you're unsure of the appropriate <a
href="{@docRoot}guide/appendix/api-levels.html">API Level</a> to use,
copy the API Level listed for the Build Target you selected in the Target tab.</li>
</ul>
</li>
</ul>
</li>
<li>Click <strong>Finish</strong>.</li>
</ol>
<p class="note"><strong>Tip:</strong>
You can also start the New Project Wizard from the <em>New</em> icon in the toolbar.</p>
<p>Once you complete the New Project Wizard, ADT creates the following
folders and files in your new project:</p>
<dl>
<dt><code>src/</code></dt>
<dd>Includes your stub Activity Java file. All other Java files for your application
go here.</dd>
<dt><code><em>&lt;Android Version&gt;</em>/</code> (e.g., <code>Android 1.1/</code>)</dt>
<dd>Includes the <code>android.jar</code> file that your application will build against.
This is determined by the build target that you have chosen in the <em>New Project
Wizard</em>.</dd>
<dt><code>gen/</code></dt>
<dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file
and interfaces created from AIDL files.</dd>
<dt><code>assets/</code></dt>
<dd>This is empty. You can use it to store raw asset files. </dd>
<dt><code>res/</code></dt>
<dd>A folder for your application resources, such as drawable files, layout files, string
values, etc. See
<a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>.</dd>
<dt><code>AndroidManifest.xml</code></dt>
<dd>The Android Manifest for your project. See
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml
File</a>.</dd>
<dt><code>default.properties</code></dt>
<dd>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 &mdash; to edit project properties,
right-click the project folder and select "Properties".</dd>
</dl>
<h2 id="AVD">Creating an AVD</h2>
<p>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.</p>
<p>To create an AVD from Eclipse:</p>
<ol>
<li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and
AVD Manager icon in the Eclipse toolbar.</p>
</li>
<li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
<strong>New</strong> to create a new AVD.</li>
<li>Fill in the details for the AVD.
<p>Give it a name, a platform target, an SD card size, and
a skin (HVGA is default).</p>
<p class="note"><strong>Note:</strong> 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).</p>
</li>
<li>Click <strong>Create AVD</strong>.</li>
</ol>
<p>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 <strong>Start</strong>.</p>
<p>For more information about AVDs, read the
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
documentation.</p>
<h2 id="Running">Running Your Application</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Use the Emulator to Test Different Configurations</h2>
<p>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.</p>
</div>
</div>
<p>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.</p>
<h3 id="RunningOnEmulator">Running on the emulator</h3>
<p>Before you can run your application on the Android Emulator,
you <strong>must</strong> <a href="#AVD">create an AVD</a>.</p>
<p>To run (or debug) your application, select <strong>Run</strong> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin
will automatically create a default launch configuration for the project. Eclipse will then perform
the following:</p>
<ol>
<li>Compile the project (if there have been changes since the last build).</li>
<li>Create a default launch configuration (if one does not already exist for the
project).</li>
<li>Install and start the application on an emulator (or device), based on the Deployment
Target
defined by the run configuration.
<p>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 <a href="#AutoAndManualTargetModes">Automatic and manual
target modes</a> below.</p>
</li>
</ol>
<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the
debugger is attached, Eclipse will open the Debug perspective.</p>
<p>To set or change the launch configuration used for your project, use the launch configuration
manager.
See <a href="#RunConfig">Creating a Run Configuration</a> for information.</p>
<p>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 <a
href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test
your application on each one.</p>
<h3 id="RunningOnDevice">Running on a device</h3>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Declare your application as debuggable in your manifest</li>
<li>Enable USB Debugging on your device</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
Development</a> for more information.</p>
<p>Once set up and your device is connected via USB, install your application on the device by
selecting <strong>Run</strong> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar.</p>
<h2 id="RunConfig">Creating a Run Configuration</h2>
<p>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 <em>Android Application</em>, 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.</p>
<p>To create or modify a launch configuration, follow these steps as appropriate
for your Eclipse version:</p>
<ol>
<li>Open the run configuration manager.
<ul>
<li>In Eclipse 3.3 (Europa), select <strong>Run</strong> &gt;
<strong>Open Run Dialog</strong> (or <strong>Open Debug Dialog</strong>)
</li>
<li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>&gt;
<strong>Run Configurations</strong> (or
<strong>Debug Configurations</strong>)
</li>
</ul>
</li>
<li>Expand the <strong>Android Application</strong> item and create a new
configuration or open an existing one.
<ul>
<li>To create a new configuration:
<ol>
<li>Select <strong>Android Application</strong> and click the <em>New launch
configuration</em>
icon above the list (or, right-click <strong>Android Application</strong> and click
<strong>New</strong>).</li>
<li>Enter a Name for your configuration.</li>
<li>In the Android tab, browse and select the project you'd like to run with the
configuration.</li>
</ol>
<li>To open an existing configuration, select the configuration name from the list
nested below <strong>Android Application</strong>.</li>
</ul>
</li>
<li>Adjust your desired launch configuration settings.
<p>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 <a href="#AutoAndManualTargetModes">Automatic and manual target
modes</a>).</p>
<p>You can specify any emulator options to the Additional Emulator Command
Line Options field. For example, you could add <code>-scale 96dpi</code> 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 <a
href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>
document.</p>
</li>
</ol>
<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3>
<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
select an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p>
<ol>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ol>
<p>However, if a "preferred AVD" is selected in the run configuration, then the application
will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator
will be launched.</p>
<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser"
is presented every time that your application is run, so that you can select which AVD to use.</p>
<h2 id="Signing">Signing your Applications</h2>
<p>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).</p>
<p>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 <strong>must</strong> sign the application with your
own private key, rather than the debug key generated by the SDK tools.</p>
<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
Applications</a>, 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.</p>
<h2 id="libraryProject">Working with Library Projects</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Library project example code</h2>
<p>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.
<p style="margin-top:1em;">To download the sample applications and run them as
projects in your environment, use the <em>Android SDK and AVD Manager</em> to
download the "Samples for SDK API 8" component into your SDK. </p>
<p style="margin-top:1em;">For more information and to browse the code of the
samples, see the <a
href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain
application</a>.</p>
</div>
</div>
<p>An Android <em>library project</em> 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 <code>.apk</code> files. Multiple application projects can reference
the same library project and any single application project can reference
multiple library projects. </p>
<p>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: </p>
<ul>
<li>If you are developing multiple related applications that use some of the
same components, you could move the redundant components out of their respective
application projects and create a single, reuseable set of the same components
in a library project. </li>
<li>If you are creating an application that exists in both free and paid
versions, you could 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.</li>
</ul>
<p>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 <code>src/</code>, <code>res/</code> 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 <code>R</code> class. </p>
<p>However, a library project differs from an standard Android application
project in that you cannot compile it directly to its own <code>.apk</code> 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. </p>
<p>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 <code>.apk</code>. 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 <code>.apk</code>. This
gives your application the flexibility to either use or redefine any resource
behaviors or values that are defined in any library.</p>
<p>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. </p>
<p>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
<strong>Up</strong> and <strong>Down</strong> 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. </p>
<p>Note that a library project cannot itself reference another library project
and that, at build time, library projects are <em>not</em> 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.</p>
<p>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.
</p>
<h3 id="libraryReqts">Development requirements</h3>
<p>Android library projects are a build-time construct, so you can use them to
build a final application <code>.apk</code> that targets any API level and is
compiled against any version of the Android library. </p>
<p>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:</p>
<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools
and plaforms on which you can develop library projects.</p>
<table>
<tr>
<th>Component</th>
<th>Minimum Version</th>
</tr>
<tr>
<td>SDK Tools</td>
<td>r6 (or higher)</td>
</tr>
<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr>
<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr>
<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr>
<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr>
<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr>
</table>
<p>You can download the tools and platforms using the <em>Android SDK and AVD
Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK
Components</a>. To install or update ADT, use the Eclipse Updater as described
in <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p>
<h3 id="librarySetup">Setting up a library project</h3>
<p>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 New Project Wizard, as described in <a href="#CreatingAProject">Creating an
Android Project</a>, above. </p>
<p>When you are creating the library project, you can select any application
name, package, and set other fields as needed, as shown in the diagram below.
Click Finish to create the project in the workspace.</p>
<p>Next, set the project's Properties to indicate that it is a library project:</p>
<ol>
<li>In the <strong>Package Explorer</strong>, right-click the library project
and select <strong>Properties</strong>.</li>
<li>In the <strong>Properties</strong> window, select the "Android" properties
group at left and locate the <strong>Library</strong> properties at right. </li>
<li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li>
<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>
<p>The new project is now marked as a library project. You can begin moving
source code and resources into it, as described in the sections below. </p>
<p>You can also convert an existing application project into a library. To do
so, simply open the Properties for the project and select the "is Library"
checkbox. Other application projects can now reference the existing project as a
library project.</p>
<img src="{@docRoot}images/developing/adt-props-isLib.png" style="margin:0;padding:0;" />
<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 1.</strong>
Marking a project as an Android library project. </p>
<h4>Creating the manifest file</h4>
<p>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 <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
<p>For example, the <a
href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a>
example library project declares the Activity <code>GameActivity</code>: </p>
<pre>&lt;manifest&gt;
...
&lt;application&gt;
...
&lt;activity android:name="GameActivity" /&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<h3 id="libraryReference">Referencing a library project from an application</h3>
<p>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.</p>
<p>To add a reference to a library project, follow these steps: </p>
<ol>
<li>In the <strong>Package Explorer</strong>, right-click the dependent project
and select <strong>Properties</strong>.</li>
<li>In the <strong>Properties</strong> window, select the "Android" properties group
at left and locate the <strong>Library</strong> properties at right.</li>
<li>Click <strong>Add</strong> to open the <strong>Project Selection</strong>
dialog. </li>
<li>From the list of available library projects, select a project and click
<strong>OK</strong>.</li>
<li>When the dialog closes, click <strong>Apply</strong> in the
<strong>Properties</strong> window.</li>
<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>
<p>As soon as the Properties dialog closes, Eclipse rebuilds the project,
including the contents of the library project. </p>
<p>The figure below shows the Properties dialog that lets you add library
references and move them up and down in priority. </p>
<img src="{@docRoot}images/developing/adt-props-libRef.png" style="margin:0;padding:0;" />
<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 2.</strong>
Adding a reference to a library project in the properties of an application project. </p>
<p>If you are adding references to multiple libraries, note that you can set
their relative priority (and merge order) by selecting a library and using the
<strong>Up</strong> and <strong>Down</strong> controls. The tools merge the
referenced libraries with your application starting from lowest priority (bottom
of the list) to highest (top of the list). If more than one library defines the
same resource ID, the tools select the resource from the library with higher
priority. The application itself has highest priority and its resources are
always used in preference to identical resource IDs defined in libraries.</p>
<h4>Declaring library components in the the manifest file</h4>
<p>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 <code>&lt;activity&gt;</code>,
<code>&lt;service&gt;</code>, <code>&lt;receiver&gt;</code>,
<code>&lt;provider&gt;</code>, and so on, as well as
<code>&lt;permission&gt;</code>, <code>&lt;uses-library&gt;</code>, and similar
elements.</p>
<p>Declarations should reference the library components by their fully-qualified
package names, where appropriate. </p>
<p>For example, the <a
href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a>
example application declares the library Activity <code>GameActivity</code>
like this: </p>
<pre>&lt;manifest&gt;
...
&lt;application&gt;
...
&lt;activity android:name="com.example.android.tictactoe.library.GameActivity" /&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<p>For more information about the manifest file, see the documentation for <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
<h3 id="considerations">Development considerations</h3>
<p>As you develop your library project and dependent applications, keep the
points listed below in mind.</p>
<p><strong>Resource conflicts</strong></p>
<p>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.</p>
<p><strong>Using prefixes to avoid resource conflicts</strong></p>
<p>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). </p>
<p><strong>No export of library project to JAR</strong></p>
<p>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.</p>
<p><strong>A library project can include a JAR library</strong></p>
<p>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. </p>
<p><strong>A library project can depend on an external JAR library</strong></p>
<p>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 <a
href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code>&lt;uses-library&gt;</code></a>
element. </p>
<p><strong>Library project can not include raw assets</strong></p>
<p>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
<code>assets/</code> directory of the application project
itself.</p>
<p><strong>Targeting different Android platform versions in library project and
application project</strong></p>
<p>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 <a href="{@docRoot}guide/appendix/api-levels.html">API level</a>
that is the same as &mdash; or lower than &mdash; 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.</p>
<p><strong>No restriction on library package name</strong></p>
<p>There is no requirement for the package name of a library to be the same as
that of applications that use it.</p>
<p><strong>Multiple R classes in gen/ folder of application project</strong></p>
<p>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
<code>R</code> class, named according to the library's package name. The
<code>R</code> 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.</p>
<p><strong>Testing a library project</strong></p>
<p>There are two recommended ways of setting up testing on code and resources in
a library project: </p>
<ul>
<li>You can set up a <a
href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a>
that instruments an application project that depends on the library project. You
can then add tests to the project for library-specific features.</li>
<li>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.</li>
</ul>
<p><strong>Library project storage location</strong></p>
<p>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.</p>
<h3 id="libraryMigrating">Migrating library projects to ADT 0.9.8</h3>
<p>This section provides information about how to migrate a library project
created with ADT 0.9.7 to ADT 0.9.8 (or higher). The migration is needed only if
you are developing in Eclipse with ADT and assumes that you have also upgraded
to SDK Tools r7 (or higher). </p>
<p>The way that ADT handles library projects has changed between
ADT 0.9.7 and ADT 0.9.8. Specifically, in ADT 0.9.7, the <code>src/</code>
source folder of the library was linked into the dependent application project
as a folder that had the same name as the library project. This worked because
of two restrictions on the library projects:</p>
<ul>
<li>The library was only able to contain a single source folder (excluding the
special <code>gen/</code> source folder), and</li>
<li>The source folder was required to have the name <code>src/</code> and be
stored at the root of the project.</li>
</ul>
<p>In ADT 0.9.8, both of those restrictions were removed. A library project can
have as many source folders as needed and each can have any name. Additionally,
a library project can store source folders in any location of the project. For
example, you could store sources in a <code>src/java/</code> directory. In order
to support this, the name of the linked source folders in the main project are
now called &lt;<em>library-name</em>&gt;_&lt;<em>folder-name</em>&gt; For
example: <code>MyLibrary_src/</code> or <code>MyLibrary_src_java/</code>.</p>
<p>Additionally, the linking process now flags those folders in order for ADT to
recognize that it created them. This will allow ADT to automatically migrate the
project to new versions of ADT, should they contain changes to the handling of
library projects. ADT 0.9.7 did not flag the linked source folders, so ADT 0.9.8
cannot be sure whether the old linked folders can be removed safely. After
upgrading ADT to 0.9.8, you will need to remove the old linked folders manually
in a simple two-step process, as described below.</p>
<p>Before you begin, make sure to create a backup copy of your application or
save the latest version to your code version control system. This ensures that
you will be able to easily revert the migration changes in case there is a
problem in your environment.</p>
<p>When you first upgrade to ADT 0.9.8, your main project will look as shown
below, with two linked folders (in this example, <code>MyLibrary</code> and
<code>MyLibrary_src</code> &mdash; both of which link to
<code>MyLibrary/src</code>. Eclipse shows an error on one of them because they
are duplicate links to a single class.</p>
<img src="{@docRoot}images/developing/lib-migration-0.png" alt="">
<p>To fix the error, remove the linked folder that <em>does not</em> contain the
<code>_src</code> suffix. </p>
<ol>
<li>Right click the folder that you want to remove (in this case, the
<code>MyLibrary</code> folder) and choose <strong>Build Path</strong> &gt;
<strong>Remove from Build Path</strong>, as shown below.</li>
<img src="{@docRoot}images/developing/lib-migration-1.png" style="height:600px"
alt="">
<li>Next, When asked about unlinking the folder from the project, select
<strong>Yes</strong>, as shown below.</li>
<img src="{@docRoot}images/developing/lib-migration-2.png" alt="">
</ol>
<p>This should resolve the error and migrate your library project to the new
ADT environment. </p>
<h2 id="Tips">Eclipse Tips</h2>
<h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3>
<p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example,
when in a function with a String argument called &quot;zip&quot;, you can get
information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will
start dmTrace. </p>
<p>Open a code execution window, select <strong>Window</strong> &gt; <strong>Show
View</strong> &gt; <strong>Display</strong> 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().)</p>
<p>If you are currently paused on a breakpoint, you can simply highlight and execute
a piece of source code by pressing CTRL + SHIFT + D. </p>
<p>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. </p>
<p>Here are a few sample inputs and responses in Eclipse using the Display window.</p>
<table width="100%" border="1">
<tr>
<th scope="col">Input</th>
<th scope="col">Response</th>
</tr>
<tr>
<td><code>zip</code></td>
<td><code>(java.lang.String)
/work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td>
</tr>
<tr>
<td><code>zip.endsWith(&quot;.zip&quot;)</code></td>
<td><code>(boolean) true</code></td>
</tr>
<tr>
<td><code>zip.endsWith(&quot;.jar&quot;)</code></td>
<td><code>(boolean) false</code></td>
</tr>
</table>
<p>You can also execute arbitrary code when not debugging by using a scrapbook page.
Search the Eclipse documentation for &quot;scrapbook&quot;.</p>
<h3>Running DDMS Manually</h3>
<p>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. (<strong>Note: </strong>Be sure that you
have first started <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a>). </p>
<!-- TODO: clean this up and expand it to cover more wizards and features
<h3>ADT Wizards</h3>
<p>Notice that the "New Android Project" wizard has been expanded to use the multi-platform
capabilities of the new SDK.</p>
<p>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 menu, a
new strings file, etc.</p>
<p>Both wizards are available via <strong>File > New</strong> and new icons in the main
Eclipse toolbar (located to the left of the Debug and Run icons).
If you do not see the new icons, you may need to select <strong>Window > Reset
Perspective</strong> from the Java perspective.</p>
-->
base/docs/html/guide/developing/index.html
+8
View File
@@ -0,0 +1,8 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=../index.html">
</head>
<body>
<a href="../index.html">click here</a> if you are not redirected.
</body>
</html>
base/docs/html/guide/developing/other-ide.jd
+937
View File
@@ -0,0 +1,937 @@
page.title=Developing In Other IDEs
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#CreatingAProject">Creating an Android Project</a></li>
<li><a href="#Signing">Preparing to Sign Your Application</a></li>
<li><a href="#Building">Building Your Application</a>
<ol>
<li><a href="#DebugMode">Building in debug mode</a></li>
<li><a href="#ReleaseMode">Building in release mode</a></li>
</ol>
</li>
<li><a href="#AVD">Creating an AVD</a></li>
<li><a href="#Running">Running Your Application</a>
<ol>
<li><a href="#RunningOnEmulator">Running on the emulator</a></li>
<li><a href="#RunningOnDevice">Running on a device</a></li>
</ol>
</li>
<li><a href="#libraryProject">Working with Library Projects</a>
<ol>
<li><a href="#libraryReqts">Development requirements</a></li>
<li><a href="#librarySetup">Setting up a library project</a></li>
<li><a href="#libraryReference">Referencing a library project</a></li>
<li><a href="#depAppBuild">Building a dependent application project</a></li>
<li><a href="#considerations">Development considerations</a></li>
</ol>
</li>
<li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li>
<li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li>
<li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></li>
</ol>
</div>
</div>
<p>The recommended way to develop an Android application is to use
<a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the ADT plugin</a>.
The ADT plugin provides editing, building, debugging, and .apk packaging and signing functionality
integrated right into the IDE.</p>
<p>However, if you'd rather develop your application in another IDE, such as IntelliJ,
or in a basic editor, such as Emacs, you can do that instead. The SDK
includes all the tools you need to set up an Android project, build it, debug it and then
package it for distribution. This document is your guide to using these tools.</p>
<h2 id="EssentialTools">Essential Tools</h2>
<p>When developing in IDEs or editors other than Eclipse, you'll require
familiarity with the following Android SDK tools:</p>
<dl>
<dt><a href="{@docRoot}guide/developing/tools/othertools.html#android">android</a></dt>
<dd>To create/update Android projects and to create/move/delete AVDs.</dd>
<dt><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></dt>
<dd>To run your Android applications on an emulated Android platform.</dd>
<dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt>
<dd>To interface with your emulator or connected device (install apps,
shell the device, issue commands, etc.).
</dd>
</dl>
<p>In addition to the above tools, included with the SDK, you'll use the following
open source and third-party tools:</p>
<dl>
<dt>Ant</dt>
<dd>To compile and build your Android project into an installable .apk file.</dd>
<dt>Keytool</dt>
<dd>To generate a keystore and private key, used to sign your .apk file.</dd>
<dt>Jarsigner (or similar signing tool)</dt>
<dd>To sign your .apk file with a private key generated by keytool.</dd>
</dl>
<p>In the topics that follow, you'll be introduced to each of these tools as necessary.
For more advanced operations, please read the respective documentation for each tool.</p>
<h2 id="CreatingAProject">Creating an Android Project</h2>
<p>To create an Android project, you must use the <code>android</code> tool. When you create
a new project with <code>android</code>, it will generate a project directory
with some default application files, stub files, configuration files and a build file.</p>
<h3 id="CreatingANewProject">Creating a new Project</h3>
<p>If you're starting a new project, use the <code>android create project</code>
command to generate all the necessary files and folders.</p>
<p>To create a new Android project, open a command-line,
navigate to the <code>tools/</code> directory of your SDK and run:</p>
<pre>
android create project \
--target <em>&lt;target_ID&gt;</em> \
--name <em>&lt;your_project_name&gt;</em> \
--path <em>path/to/your/project</em> \
--activity <em>&lt;your_activity_name&gt;</em> \
--package <em>&lt;your_package_namespace&gt;</em>
</pre>
<ul>
<li><code>target</code> 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: <code>android list targets</code>.</li>
<li><code>name</code> 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.</li>
<li><code>path</code> is the location of your project directory. If the directory does not exist,
it will be created for you.</li>
<li><code>activity</code> is the name for your default {@link android.app.Activity} class. This
class file
will be created for you inside
<code><em>&lt;path_to_your_project&gt;</em>/src/<em>&lt;your_package_namespace_path&gt;</em>/</code>
.
This will also be used for your .apk filename unless you provide a the <code>name</code>.</li>
<li><code>package</code> is the package namespace for your project, following the same rules as
for
packages in the Java programming language.</li>
</ul>
<p>Here's an example:</p>
<pre>
android create project \
--target 1 \
--name MyAndroidApp \
--path ./MyAndroidAppProject \
--activity MyAndroidAppActivity \
--package com.example.myandroid
</pre>
<p>The tool generates the following files and directories:</p>
<ul>
<li><code>AndroidManifest.xml</code> - The application manifest file,
synced to the specified Activity class for the project.</li>
<li><code>build.xml</code> - Build file for Ant.</li>
<li><code>default.properties</code> - Properties for the build system. <em>Do not modify
this file</em>.</li>
<li><code>build.properties</code> - 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.</li>
<li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class
you specified during project creation.</li>
<li><code>bin/</code> - Output directory for the build script.</li>
<li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>.
</li>
<li><code>libs/</code> - Holds private libraries.</li>
<li><code>res/</code> - Holds project resources.</li>
<li><code>src/</code> - Holds source code.</li>
<li><code>tests/</code> - Holds a duplicate of all-of-the-above, for testing purposes.</li>
</ul>
<p>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 <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
(adb) &mdash; located in the SDK <code>platform-tools/</code> directory &mdash; to send your
application
to the emulator (discussed later). So you need access between your project solution and
the <code>platform-tools/</code> folder.</p>
<p class="caution"><strong>Caution:</strong> 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.)</p>
<h3 id="UpdatingAProject">Updating a project</h3>
<p>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
<code>android update project</code> 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 <code>--target</code> option) and the project name (with the <code>--name</code>
option). The <code>android</code> 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.</p>
<p>To update an existing Android project, open a command-line
and navigate to the <code>tools/</code> directory of your SDK. Now run:</p>
<pre>
android update project --name <em>&lt;project_name&gt;</em> --target <em>&lt;target_ID&gt;</em>
--path <em>&lt;path_to_your_project&gt;</em>
</pre>
<ul>
<li><code>target</code> 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: <code>android list targets</code>.</li>
<li><code>path</code> is the location of your project directory.</li>
<li><code>name</code> is the name for the project. This is optional&mdash;if you're not
changing the project name, you don't need this.</li>
</ul>
<p>Here's an example:</p>
<pre>
android update project --name MyApp --target 2 --path ./MyAppProject
</pre>
<h2 id="Signing">Preparing to Sign Your Application</h2>
<p>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 <em>debug key</em> (for immediate testing on an emulator or development device)
or with a <em>private key</em> (for application distribution).</p>
<p>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 <strong>must</strong> sign the application with your
own private key, rather than the debug key generated by the SDK tools. </p>
<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
Applications</a>, which provides a thorough guide to application signing on Android
and what it means to you as an Android application developer.</p>
<h2 id="Building">Building Your Application</h2>
<p>There are two ways to build your application: one for testing/debugging your application
&mdash; <em>debug mode</em> &mdash; and one for building your final package for release &mdash;
<em>release mode</em>. As described in the previous
section, your application must be signed before it can be installed on an emulator
or device.</p>
<p>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 <em>unsigned</em>, so you must manually
sign it with your own private key, using Keytool and Jarsigner.</p>
<p>It's important that you read and understand
<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, 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.</p>
<p>If you don't have Ant, you can obtain it from the
<a href="http://ant.apache.org/">Apache Ant home page</a>. 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.</p>
<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install
in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of
the space. To fix the problem, you can specify the JAVA_HOME variable like this:
<code>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;</code>. The easiest solution, however, is to
install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p>
<h3 id="DebugMode">Building in debug mode</h3>
<p>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
{@code 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.</p>
<p>To build in debug mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in debug mode:
<pre>ant debug</pre>
<p>This creates your debug .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</em>-debug.apk</code>. The file
is already signed with the debug key and has been aligned with {@code zipalign}.</p>
</li>
</ol>
<p>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.</p>
<p>To install and run your application on an emulator, see the following section
about <a href="#Running">Running Your Application</a>.</p>
<h3 id="ReleaseMode">Building in release mode</h3>
<p>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.</p>
<p>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
{@code zipalign} tool. There are two approaches to building in release 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.</p>
<h4 id="ManualReleaseMode">Build unsigned</h4>
<p>If you build your application <em>unsigned</em>, then you will need to
manually sign and align the package.</p>
<p>To build an <em>unsigned</em> .apk in release mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in release mode:
<pre>ant release</pre>
</li>
</ol>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</em>-unsigned.apk</code>.</p>
<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point
and can't be installed until signed with your private key.</p>
<p>Once you have created the unsigned .apk, your next step is to sign the .apk
with your private key and then align it with {@code zipalign}. To complete this procedure,
read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>When your .apk has been signed and aligned, it's ready to be distributed to end-users.</p>
<h4 id="AutoReleaseMode">Build signed and aligned</h4>
<p>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 {@code 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.</p>
<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
you enter during the build process <strong>will be visible</strong>. 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, <a href="#ManualReleaseMode">build unsigned</a> and then
continue
with <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>To specify your keystore and alias, open the project {@code build.properties} file (found in the
root of the project directory) and add entries for {@code key.store} and {@code key.alias}.
For example:</p>
<pre>
key.store=path/to/my.keystore
key.alias=mykeystore
</pre>
<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your project directory.</li>
<li>Use Ant to compile your project in release mode:
<pre>ant release</pre>
</li>
<li>When prompted, enter you keystore and alias passwords.
<p class="caution"><strong>Caution:</strong> As described above,
your password will be visible on the screen.</p>
</li>
</ol>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_project_name&gt;</em>-release.apk</code>.
This .apk file has been signed with the private key specified in
{@code build.properties} and aligned with {@code zipalign}. It's ready for
installation and distribution.</p>
<h4>Once built and signed in release mode</h4>
<p>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
<a href="#Running">Running Your Application</a>.
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 <em>Settings > Applications > Unknown sources</em>.)</p>
<h2 id="AVD">Creating an AVD</h2>
<p>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.</p>
<p>To create an AVD using the SDK tools:</p>
<ol>
<li>Navigate to your SDK's <code>tools/</code> directory and execute the {@code android}
tool with no arguments:
<pre>android</pre>
<p>This will launch the SDK and AVD Manager GUI.</p>
</li>
<li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
<strong>New</strong>
to create a new AVD.</li>
<li>Fill in the details for the AVD.
<p>Give it a name, a platform target, an SD card size, and
a skin (HVGA is default).</p>
<p class="note"><strong>Note:</strong> 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).</p>
</li>
<li>Click <strong>Create AVD</strong>.</li>
</ol>
<p>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 <strong>Start</strong>.</p>
<p>For more information about AVDs, read the
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
documentation.</p>
<h2 id="Running">Running Your Application</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Use the Emulator to Test Different Configurations</h2>
<p>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.</p>
</div>
</div>
<p>Running your application on a virtual or real device takes just a couple steps. Remember to
first <a href="#Building">build your application</a>.</p>
<h3 id="RunningOnEmulator">Running on the emulator</h3>
<p>Before you can run your application on the Android Emulator,
you must <a href="#AVD">create an AVD</a>.</p>
<p>To run your application:</p>
<ol>
<li><strong>Open the SDK and AVD Manager and launch a virtual device</strong></li>
<p>From your SDK's <code>tools/</code> directory, execute the {@code android} tool with no
arguments:
<pre>android</pre>
<p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
</li>
<li><strong>Install your application</strong>
<p>From your SDK's <code>platform-tools/</code> directory, install the {@code .apk} on the
emulator:
<pre>adb install <em>&lt;path_to_your_bin&gt;</em>.apk</pre>
<p>Your APK file (signed with either a release or debug key) is in your project {@code bin/}
directory after you <a href="#Building">build your application</a>.</p>
<p>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 <code>-s</code> option. For example:</p>
<pre>adb -s emulator-5554 install <em>path/to/your/app</em>.apk</pre>
<p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
</li>
</ol>
<p>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.</p>
<p>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 <a
href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test
your application on each one.</p>
<p class="note"><strong>Tip:</strong> If you have <em>only one</em> 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 <em>install mode</em>:
<code>ant install</code>. This will build your application, sign it with the debug key,
and install it on the currently running emulator.</p>
<h3 id="RunningOnDevice">Running on a device</h3>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Declare your application as debuggable in your manifest</li>
<li>Enable USB Debugging on your device</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
Development</a> for more information.</p>
<p>Once your device is set up and connected via USB, navigate to your
SDK's <code>platform-tools/</code> directory and install the <code>.apk</code> on the device:
<pre>adb -d install <em>path/to/your/app</em>.apk</pre>
<p>The {@code -d} flag specifies that you want to use the attached device (in case you also
have an emulator running).</p>
<p>For more information on the tools used above, please see the following documents:</p>
<ul>
<li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li>
<li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li>
<li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li>
</ul>
<h2 id="libraryProject">Working with Library Projects</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Library project example code</h2>
<p>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.
<p style="margin-top:1em;">To download the sample applications and run them as
projects in your environment, use the <em>Android SDK and AVD Manager</em> to
download the "Samples for SDK API 8" component into your SDK. </p>
<p style="margin-top:1em;">For more information and to browse the code of the
samples, see the <a
href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain
application</a>.</p>
</div>
</div>
<p>An Android <em>library project</em> 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 <code>.apk</code> files. Multiple application projects can reference
the same library project and any single application project can reference
multiple library projects. </p>
<p>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: </p>
<ul>
<li>If you are developing multiple related applications that use some of the
same components, you could move the redundant components out of their respective
application projects and create a single, reuseable set of the same components
in a library project. </li>
<li>If you are creating an application that exists in both free and paid
versions, you could 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.</li>
</ul>
<p>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 <code>src/</code>, <code>res/</code> 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 <code>R</code> class. </p>
<p>However, a library project differs from an standard Android application
project in that you cannot compile it directly to its own <code>.apk</code> 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. </p>
<p>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 <code>.apk</code>. 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 <code>.apk</code>. This
gives your application the flexibility to either use or redefine any resource
behaviors or values that are defined in any library.</p>
<p>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.
<p>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. </p>
<p>Note that a library project cannot itself reference another library project
and that, at build time, library projects are <em>not</em> 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.</p>
<p>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.
</p>
<h3 id="libraryReqts">Development requirements</h3>
<p>Android library projects are a build-time construct, so you can use them to
build a final application <code>.apk</code> that targets any API level and is
compiled against any version of the Android library. </p>
<p>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:</p>
<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools
and plaforms on which you can develop library projects.</p>
<table>
<tr>
<th>Component</th>
<th>Minimum Version</th>
</tr>
<tr>
<td>SDK Tools</td>
<td>r6 (or higher)</td>
</tr>
<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr>
<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr>
<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr>
<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr>
<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr>
</table>
<p>You can download the tools and platforms using the <em>Android SDK and AVD
Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK
Components</a>.</p>
<h3 id="librarySetup">Setting up a new library project</h3>
<p>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 <code>android</code> tool to generate a new library project with all of the
necessary files and folders. </p>
<h4>Creating a library project</h4>
<p>To create a new library project, navigate to the <code>&lt;sdk&gt;/tools/</code> directory
and use this command:</p>
<pre class="no-pretty-print" style="color:black">
android create lib-project --name <em>&lt;your_project_name&gt;</em> \
--target <em>&lt;target_ID&gt;</em> \
--path <em>path/to/your/project</em> \
--package <em>&lt;your_library_package_namespace&gt;</em>
</pre>
<p>The <code>create lib-project</code> 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
<code>default.properties</code> file: </p>
<pre class="no-pretty-print" style="color:black">android.library=true</pre>
<p>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.</p>
<p>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
<code>android.library=true</code> property to the application's
<code>default.properties</code> file. </p>
<h4>Creating the manifest file</h4>
<p>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 <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
<p>For example, the <a
href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a>
example library project declares the Activity <code>GameActivity</code>: </p>
<pre>&lt;manifest&gt;
...
&lt;application&gt;
...
&lt;activity android:name="GameActivity" /&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<h4>Updating a library project</h4>
<p>If you want to update the build properties (build target, location) of the
library project, use this command: </p>
<pre>
android update lib-project \
--target <em>&lt;target_ID&gt;</em> \
--path <em>path/to/your/project</em>
</pre>
<h3 id="libraryReference">Referencing a library project from an application</h3>
<p>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.</p>
<p>To add a reference to a library project, navigate to the <code>&lt;sdk&gt;/tools/</code> directory
and use this command:</p>
<pre>
android update lib-project \
--target <em>&lt;target_ID&gt;</em> \
--path <em>path/to/your/project</em>
--library <em>path/to/library_projectA</em>
</pre>
<p>This command updates the application project's build properties to include a
reference to the library project. Specifically, it adds an
<code>android.library.reference.<em>n</em></code> property to the project's
<code>default.properties</code> file. For example: </p>
<pre class="no-pretty-print" style="color:black">
android.library.reference.1=path/to/library_projectA
</pre>
<p>If you are adding references to multiple libraries, note that you can set
their relative priority (and merge order) by manually editing the
<code>default.properties</code> file and adjusting the each reference's
<code>.<em>n</em></code> index as appropriate. For example, assume these
references: </p>
<pre class="no-pretty-print" style="color:black">
android.library.reference.1=path/to/library_projectA
android.library.reference.2=path/to/library_projectB
android.library.reference.3=path/to/library_projectC
</pre>
<p>You can reorder the references to give highest priority to
<code>library_projectC</code> in this way:</p>
<pre class="no-pretty-print" style="color:black">
android.library.reference.2=path/to/library_projectA
android.library.reference.3=path/to/library_projectB
android.library.reference.1=path/to/library_projectC
</pre>
<p>Note that the <code>.<em>n</em></code> index in the references
must begin at "1" and increase uniformly without "holes". References
appearing in the index after a hole are ignored. </p>
<p>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.</p>
<h4>Declaring library components in the the manifest file</h4>
<p>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 <code>&lt;activity&gt;</code>,
<code>&lt;service&gt;</code>, <code>&lt;receiver&gt;</code>,
<code>&lt;provider&gt;</code>, and so on, as well as
<code>&lt;permission&gt;</code>, <code>&lt;uses-library&gt;</code>, and similar
elements.</p>
<p>Declarations should reference the library components by their fully-qualified
package names, where appropriate. </p>
<p>For example, the
<a href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a>
example application declares the library Activity <code>GameActivity</code>
like this: </p>
<pre>&lt;manifest&gt;
...
&lt;application&gt;
...
&lt;activity android:name="com.example.android.tictactoe.library.GameActivity" /&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;</pre>
<p>For more information about the manifest file, see the documentation for <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
<h3 id="depAppBuild">Building a dependent application</h3>
<p>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
<a href="#Building">Building Your Application</a>, 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. </p>
<h3 id="considerations">Development considerations</h3>
<p>As you develop your library project and dependent applications, keep the
points listed below in mind.</p>
<p><strong>Resource conflicts</strong></p>
<p>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.</p>
<p><strong>Using prefixes to avoid resource conflicts</strong></p>
<p>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). </p>
<p><strong>No export of library project to JAR</strong></p>
<p>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.</p>
<p><strong>A library project can include a JAR library</strong></p>
<p>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 <code>.apk</code>. </p>
<p><strong>A library project can depend on an external JAR library</strong></p>
<p>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 <a
href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code>&lt;uses-library&gt;</code></a>
element. </p>
<p><strong>Library project cannot include raw assets</strong></p>
<p>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
<code>assets/</code> directory of the application project
itself.</p>
<p><strong>Targeting different Android platform versions in library project and
application project</strong></p>
<p>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 <a href="{@docRoot}guide/appendix/api-levels.html">API level</a>
that is the same as &mdash; or lower than &mdash; 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.</p>
<p><strong>No restriction on library package name</strong></p>
<p>There is no requirement for the package name of a library to be the same as
that of applications that use it.</p>
<p><strong>Multiple R classes in gen/ folder of application project</strong></p>
<p>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
<code>R</code> class, named according to the library's package name. The
<code>R</code> 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.</p>
<p><strong>Testing a library project</strong></p>
<p>There are two recommended ways of setting up testing on code and resources in
a library project: </p>
<ul>
<li>You can set up a <a
href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a>
that instruments an application project that depends on the library project. You
can then add tests to the project for library-specific features.</li>
<li>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.</li>
</ul>
<p><strong>Library project storage location</strong></p>
<p>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.</p>
<h2 id="AttachingADebugger">Attaching a Debugger to Your Application</h2>
<p>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. </p>
<p>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:</p>
<ol>
<li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor
Server (DDMS)</a> tool, </strong> which
acts as a port forwarding service between your IDE and the emulator.</li>
<li><strong>Set
optional debugging configurations on
your emulator</strong>, 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.</li>
<li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> Read
about <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">
Configuring Your IDE to Attach to the Debugging Port</a>. </li>
</ol>
base/docs/html/guide/developing/testing/index.jd
+36
View File
@@ -0,0 +1,36 @@
page.title=Testing Overview
@jd:body
<p>
Android includes powerful tools for setting up and running test applications.
Whether you are working in Eclipse with ADT or working from the command line, these tools
help you set up and run your tests within an emulator or the device you are targeting.
The documents listed below explain how to work with the tools in your development environment.
</p>
<p>
If you aren't yet familiar with the Android testing framework, please read the topic
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>
before you get started.
For a step-by-step introduction to Android testing, try the <a
href="{@docRoot}resources/tutorials/testing/helloandroid_test.html">Hello, Testing</a>
tutorial, which introduces basic testing concepts and procedures.
For a more advanced tutorial, try <a
href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>,
which guides you through a more complex testing scenario.
</p>
<dl>
<dt><a href="testing_eclipse.html">Testing in Eclipse, with ADT</a></dt>
<dd>
The ADT plugin lets you quickly set up and manage test projects directly in
the Eclipse UI. Once you have written your tests, you can build and run them and
then see the results in the Eclipse JUnit view. You can also use the SDK command-line
tools to execute your tests if needed.
</dd>
<dt><a href="testing_otheride.html">Testing in Other IDEs</a></dt>
<dd>
The SDK command-line tools provide the same capabilities as the ADT plugin. You can
use them to set up and manage test projects, build your test application,
run your tests, and see the results. You use
the <code>android</code> tool to create and manage test projects, the Ant build system
to compile them, and the <code>adb</code> tool to install and run them.
</dd>
</dl>
base/docs/html/guide/developing/testing/testing_eclipse.jd
+530
View File
@@ -0,0 +1,530 @@
page.title=Testing In Eclipse, with ADT
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#CreateTestProjectEclipse">Creating a Test Project</a></li>
<li><a href="#CreateTestAppEclipse">Creating a Test Package</a></li>
<li><a href="#RunTestEclipse">Running Tests</a></li>
</ol>
</div>
</div>
<p>
This topic explains how create and run tests of Android applications in Eclipse with ADT.
Before you read this topic, you should read about how to create a Android application with the
basic processes for creating and running applications with ADT, as described in
<a href="{@docRoot}guide/developing/eclipse-adt.html">Developing In Eclipse, with ADT</a>.
You may also want to read
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
which provides an overview of the Android testing framework.
</p>
<p>
ADT provides several features that help you set up and manage your testing environment
effectively:
</p>
<ul>
<li>
It lets you quickly create a test project and link it to the application under test.
When it creates the test project, it automatically inserts the necessary
<code>&lt;instrumentation&gt;</code> element in the test package's manifest file.
</li>
<li>
It lets you quickly import the classes of the application under test, so that your
tests can inspect them.
</li>
<li>
It lets you create run configurations for your test package and include in
them flags that are passed to the Android testing framework.
</li>
<li>
It lets you run your test package without leaving Eclipse. ADT builds both the
application under test and the test package automatically, installs them if
necessary to your device or emulator, runs the test package, and displays the
results in a separate window in Eclipse.
</li>
</ul>
<p>
If you are not developing in Eclipse or you want to learn how to create and run tests from the
command line, see
<a href="{@docRoot}guide/developing/testing/testing_otheride.html">Testing in Other IDEs</a>.
</p>
<h2 id="CreateTestProjectEclipse">Creating a Test Project</h2>
<p>
To set up a test environment for your Android application, you must first create a separate
project that holds the test code. The new project follows the directory structure
used for any Android application. It includes the same types of content and files, such as
source code, resources, a manifest file, and so forth. The test package you
create is connected to the application under test by an
<a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">
<code>&lt;instrumentation&gt;</code></a> element in its manifest file.
</p>
<p>
The <em>New Android Test Project</em> dialog makes it easy for you to generate a
new test project that has the proper structure, including the
<code>&lt;instrumentation&gt;</code> element in the manifest file. You can use the New
Android Test Project dialog to generate the test project at any time. The dialog appears
just after you create a new Android main application project, but you can also run it to
create a test project for a project that you created previously.
</p>
<p>
To create a test project in Eclipse with ADT:
</p>
<ol>
<li>
In Eclipse, select <strong>File &gt; New &gt; Other</strong>. This opens the <em>Select a
Wizard</em> dialog.
</li>
<li>
In the dialog, in the <em>Wizards</em> drop-down list, find the entry for Android, then
click the toggle to the left. Select <strong>Android Test Project</strong>, then at the
bottom of the dialog click <strong>Next</strong>. The <em>New Android Test Project</em>
wizard appears.
</li>
<li>
Next to <em>Test Project Name</em>, enter a name for the project. You may use any name,
but you may want to associate the name with the project name for the application under test.
One way to do this is to take the application's project name, append the string "Test" to
it, and then use this as the test package project name.
<p>
The name becomes part of the suggested project path, but you can change this in the
next step.
</p>
</li>
<li>
In the <em>Content</em> panel, examine the suggested path to the project.
If <em>Use default location</em> is set, then the wizard will suggest a path that is
a concatenation of the workspace path and the project name you entered. For example,
if your workspace path is <code>/usr/local/workspace</code> and your project name is
<code>MyTestApp</code>, then the wizard will suggest
<code>/usr/local/workspace/MyTestApp</code>. To enter your own
choice for a path, unselect <em>Use default location</em>, then enter or browse to the
path where you want your project.
<p>
To learn more about choosing the location of test projects, please read
<a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjectPaths">
Testing Fundamentals</a>.
</p>
</li>
<li>
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).
</li>
<li>
In the Build Target panel, select the Android SDK platform that the application under test
uses.
</li>
<li>
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.
</li>
</ol>
<h2 id="CreateTestAppEclipse">Creating a Test Package</h2>
<p>
Once you have created a test project, you populate it with a test package. This package does not
require an Activity, although you can define one if you wish. Although your test package can
combine Activity classes, test case classes, or ordinary classes, your main test case
should extend one of the Android test case classes or JUnit classes, because these provide the
best testing features.
</p>
<p>
Test packages do not need to have an Android GUI. When you run the package in
Eclipse with ADT, its results appear in the JUnit view. Running tests and seeing the results is
described in more detail in the section <a href="#RunTestEclipse">Running Tests</a>.
</p>
<p>
To create a test package, start with one of Android's test case classes defined in
{@link android.test android.test}. These extend the JUnit
{@link junit.framework.TestCase TestCase} class. The Android test classes for Activity objects
also provide instrumentation for testing an Activity. To learn more about test case
classes, please read the topic <a href="{@docRoot}guide/topics/testing/testing_android.html">
Testing Fundamentals</a>.
</p>
<p>
Before you create your test package, you choose the Java package identifier you want to use
for your test case classes and the Android package name you want to use. To learn more
about this, please read
<a href="{@docRoot}guide/topics/testing/testing_android.html#PackageNames">
Testing Fundamentals</a>.
</p>
<p>
To add a test case class to your project:
</p>
<ol>
<li>
In the <em>Project Explorer</em> tab, open your test project, then open the <em>src</em>
folder.
</li>
<li>
Find the Java package identifier set by the projection creation wizard. If you haven't
added classes yet, this node won't have any children, and its icon will not be filled in.
If you want to change the identifier value, right-click the identifier and select
<strong>Refactor</strong> &gt; <strong>Rename</strong>, then enter the new name.
</li>
<li>
When you are ready, right-click the Java package identifier again and select
<strong>New</strong> &gt; <strong>Class</strong>. This displays the <em>New Java Class</em>
dialog, with the <em>Source folder</em> and <em>Package</em> values already set.
</li>
<li>
In the <em>Name</em> field, enter a name for the test case class. One way to choose a
class name is to append the string "Test" to the class of the component you are testing.
For example, if you are testing the class MyAppActivity, your test case class
name would be MyAppActivityTest. Leave the modifiers set to <em>public</em>.
</li>
<li>
In the <em>Superclass</em> field, enter the name of the Android test case class you
are extending. You can also browse the available classes.
</li>
<li>
In <em>Which method stubs would you like to create?</em>, unset all the options, then
click <strong>Finish</strong>. You will set up the constructor manually.
</li>
<li>
Your new class appears in a new Java editor pane.
</li>
</ol>
<p>
You now have to ensure that the constructor is set up correctly. Create a constructor for your
class that has no arguments; this is required by JUnit. As the first statement in this
constructor, add a call to the base class' constructor. Each base test case class has its
own constructor signature. Refer to the class documentation in the documentation for
{@link android.test} for more information.
</p>
<p>
To control your test environment, you will want to override the <code>setUp()</code> and
<code>tearDown()</code> methods:
</p>
<ul>
<li>
<code>setUp()</code>: This method is invoked before any of the test methods in the class.
Use it to set up the environment for the test (the test fixture. You can use
<code>setUp()</code> to instantiate a new Intent with the action <code>ACTION_MAIN</code>.
You can then use this intent to start the Activity under test.
</li>
<li>
<code>tearDown()</code>: This method is invoked after all the test methods in the class. Use
it to do garbage collection and to reset the test fixture.
</li>
</ul>
<p>
Another useful convention is to add the method <code>testPreconditions()</code> 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.
</p>
<p>
The Resources tab contains an
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
tutorial with more information about creating test classes and methods.
</p>
<h2 id="RunTestEclipse">Running Tests</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Running tests from the command line</h2>
<p>
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.
</p>
<p>
To run tests created in Eclipse with ADT with command-line tools, you must first
install additional files into the test project using the <code>android</code>
tool's "create test-project" option. To see how to do this, read
<a href="{@docRoot}guide/developing/testing/testing_otheride.html#CreateProject">
Testing in Other IDEs</a>.
</p>
</div>
</div>
<p>
When you run a test package in Eclipse with ADT, the output appears in the Eclipse JUnit view.
You can run the entire test package or one test case class. To do run tests, Eclipse runs the
<code>adb</code> command for running a test package, and displays the output, so there is no
difference between running tests inside Eclipse and running them from the command line.
</p>
<p>
As with any other package, to run a test package in Eclipse with ADT you must either attach a
device to your computer or use the Android emulator. If you use the emulator, you must have an
Android Virtual Device (AVD) that uses the same target as the test package.
</p>
<p>
To run a test in Eclipse, you have two choices:</p>
<ul>
<li>
Run a test just as you run an application, by selecting
<strong>Run As... &gt; Android JUnit Test</strong> from the project's context menu or
from the main menu's <strong>Run</strong> item.
</li>
<li>
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.
<p>
Creating and running test configurations is described in the next section.
</p>
</li>
</ul>
<p>
To create and run a test suite using a run configuration:
</p>
<ol>
<li>
In the Package Explorer, select the test project, then from the main menu, select
<strong>Run &gt; Run Configurations...</strong>. The Run Configurations dialog appears.
</li>
<li>
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 of the test classes in your project.
</li>
<li>
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.
<p>
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.
</p>
</li>
<li>
Now click the Target tab.
<ul>
<li>
Optional: If you are using the emulator, click Automatic, then in the Android
Virtual Device (AVD) selection table, select an existing AVD.
</li>
<li>
In the Emulator Launch Parameters pane, set the Android emulator flags you want to
use. These are documented in the topic
<a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">
Android Emulator</a>.
</li>
</ul>
</li>
<li>
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.
</li>
<li>
Optional: Add the configuration to the Run toolbar and the <strong>Favorites</strong>
menu: in the Display in Favorites pane click the checkbox next to Run.
</li>
<li>
Optional: To add this configuration to the <strong>Debug</strong> menu and toolbar, click
the checkbox next to Debug.
</li>
<li>
To save your settings, click Close.<br/>
<p class="note"><strong>Note:</strong>
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.
</p>
</li>
<li>
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.
</li>
<li>
Select the test run configuration you just created. The test starts.
</li>
</ol>
<p>
The progress of your test appears in the Console view as a series of messages. Each message is
preceded by a timestamp and the <code>.apk</code> filename to which it applies. For example,
this message appears when you run a test to the emulator, and the emulator is not yet started:
</p>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Message Examples</h2>
<p>
The examples shown in this section come from the
<a href="{@docRoot}resources/samples/SpinnerTest/index.html">SpinnerTest</a>
sample test package, which tests the
<a href="{@docRoot}resources/samples/Spinner/index.html">Spinner</a>
sample application. This test package is also featured in the
<a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
tutorial.
</p>
</div>
</div>
<pre>
[<em>yyyy-mm-dd hh:mm:ss</em> - <em>testfile</em>] Waiting for HOME ('android.process.acore') to be launched...
</pre>
<p>
In the following description of these messages, <code><em>devicename</em></code> is the name of
the device or emulator you are using to run the test, and <code><em>port</em></code> is the
port number for the device. The name and port number are in the format used by the
<code><a href="{@docRoot}guide/developing/tools/adb.html#devicestatus">adb devices</a></code>
command. Also, <code><em>testfile</em></code> is the <code>.apk</code> filename of the test
package you are running, and <em>appfile</em> is the filename of the application under test.
</p>
<ul>
<li>
If you are using an emulator and you have not yet started it, then Eclipse
first starts the emulator. When this is complete, you see
the message:
<p>
<code>HOME is up on device '<em>devicename</em>-<em>port</em>'</code>
</p>
</li>
<li>
If you have not already installed your test package, then you see
the message:
<p>
<code>Uploading <em>testfile</em> onto device '<em>devicename</em>-<em>port</em>'
</code>
</p>
<p>
then the message <code>Installing <em>testfile</em></code>.
</p>
<p>
and finally the message <code>Success!</code>
</p>
</li>
</ul>
<p>
The following lines are an example of this message sequence:
</p>
<code>
[2010-07-01 12:44:40 - MyTest] HOME is up on device 'emulator-5554'<br>
[2010-07-01 12:44:40 - MyTest] Uploading MyTest.apk onto device 'emulator-5554'<br>
[2010-07-01 12:44:40 - MyTest] Installing MyTest.apk...<br>
[2010-07-01 12:44:49 - MyTest] Success!<br>
</code>
<br>
<ul>
<li>
Next, if you have not yet installed the application under test to the device or
emulator, you see the message
<p>
<code>Project dependency found, installing: <em>appfile</em></code>
</p>
<p>
then the message <code>Uploading <em>appfile</em></code> onto device
'<em>devicename</em>-<em>port</em>'
</p>
<p>
then the message <code>Installing <em>appfile</em></code>
</p>
<p>
and finally the message <code>Success!</code>
</p>
</li>
</ul>
<p>
The following lines are an example of this message sequence:
</p>
<code>
[2010-07-01 12:44:49 - MyTest] Project dependency found, installing: MyApp<br>
[2010-07-01 12:44:49 - MyApp] Uploading MyApp.apk onto device 'emulator-5554'<br>
[2010-07-01 12:44:49 - MyApp] Installing MyApp.apk...<br>
[2010-07-01 12:44:54 - MyApp] Success!<br>
</code>
<br>
<ul>
<li>
Next, you see the message
<code>Launching instrumentation <em>instrumentation_class</em> on device
<em>devicename</em>-<em>port</em></code>
<p>
<code>instrumentation_class</code> is the fully-qualified class name of the
instrumentation test runner you have specified (usually
{@link android.test.InstrumentationTestRunner}.
</p>
</li>
<li>
Next, as {@link android.test.InstrumentationTestRunner} builds a list of tests to run,
you see the message
<p>
<code>Collecting test information</code>
</p>
<p>
followed by
</p>
<p>
<code>Sending test information to Eclipse</code>
</p>
</li>
<li>
Finally, you see the message <code>Running tests</code>, which indicates that your tests
are running. At this point, you should start seeing the test results in the JUnit view.
When the tests are finished, you see the console message <code>Test run complete</code>.
This indicates that your tests are finished.
</li>
</ul>
<p>
The following lines are an example of this message sequence:
</p>
<code>
[2010-01-01 12:45:02 - MyTest] Launching instrumentation android.test.InstrumentationTestRunner on device emulator-5554<br>
[2010-01-01 12:45:02 - MyTest] Collecting test information<br>
[2010-01-01 12:45:02 - MyTest] Sending test information to Eclipse<br>
[2010-01-01 12:45:02 - MyTest] Running tests...<br>
[2010-01-01 12:45:22 - MyTest] Test run complete<br>
</code>
<br>
<p>
The test results appear in the JUnit view. This is divided into an upper summary pane,
and a lower stack trace pane.
</p>
<p>
The upper pane contains test information. In the pane's header, you see the following
information:
</p>
<ul>
<li>
Total time elapsed for the test package (labeled Finished after <em>x</em> seconds).
</li>
<li>
Number of runs (Runs:) - the number of tests in the entire test class.
</li>
<li>
Number of errors (Errors:) - the number of program errors and exceptions encountered
during the test run.
</li>
<li>
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.
</li>
<li>
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.
</li>
</ul>
<p>
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.
</p>
<p>
The results of a successful test are shown in figure 1.
</p>
<a href="{@docRoot}images/testing/eclipse_test_results.png">
<img src="{@docRoot}images/testing/eclipse_test_results.png"
alt="Messages for a successful test" height="327px" id="TestResults"/>
</a>
<p class="img-caption">
<strong>Figure 1.</strong> Messages for a successful test.
</p>
<p>
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.
</p>
<p>The results of a failed test are shown in figure 2.</p>
<a href="{@docRoot}images/testing/eclipse_test_run_failure.png">
<img src="{@docRoot}images/testing/eclipse_test_run_failure.png"
alt="" height="372px" id="TestRun"/>
</a>
<p class="img-caption">
<strong>Figure 2.</strong> Messages for a test failure.
</p>
base/docs/html/guide/developing/testing/testing_otheride.jd
+692
View File
@@ -0,0 +1,692 @@
page.title=Testing In Other IDEs
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#CreateTestProjectCommand">Working with Test Projects</a>
<ol>
<li>
<a href="#CreateTestProject">Creating a test project</a>
</li>
<li>
<a href="#UpdateTestProject">Updating a test project</a>
</li>
</ol>
</li>
<li>
<a href="#CreateTestApp">Creating a Test Package</a>
</li>
<li>
<a href="#RunTestsCommand">Running Tests</a>
<ol>
<li>
<a href="#RunTestsAnt">Quick build and run with Ant</a>
</li>
<li>
<a href="#RunTestsDevice">Running tests on a device or emulator</a>
</li>
</ol>
</li>
<li>
<a href="#AMSyntax">Using the Instrument Command</a>
<ol>
<li>
<a href="#AMOptionsSyntax">Instrument options</a>
</li>
<li>
<a href="#RunTestExamples">Instrument examples</a>
</li>
</ol>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}guide/topics/testing/testing_android.html">
Testing Fundamentals</a>
</li>
<li>
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
</li>
</ol>
</div>
</div>
<p>
This document describes how to create and run tests directly from the command line.
You can use the techniques described here if you are developing in an IDE other than Eclipse
or if you prefer to work from the command line. This document assumes that you already know how
to create a Android application in your programming environment. Before you start this
document, you should read the topic
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
which provides an overview of Android testing.
</p>
<p>
If you are developing in Eclipse with ADT, you can set up and run your tests
directly in Eclipse. For more information, please read
<a href="{@docRoot}guide/developing/testing/testing_eclipse.html">
Testing in Eclipse, with ADT</a>.
</p>
<h2 id="CreateTestProjectCommand">Working with Test Projects</h2>
<p>
You use the <code>android</code> tool to create test projects.
You also use <code>android</code> to convert existing test code into an Android test project,
or to add the <code>run-tests</code> Ant target to an existing Android test project.
These operations are described in more detail in the section <a href="#UpdateTestProject">
Updating a test project</a>. The <code>run-tests</code> target is described in
<a href="#RunTestsAnt">Quick build and run with Ant</a>.
</p>
<h3 id="CreateTestProject">Creating a test project</h3>
<p>
To create a test project with the <code>android</code> tool, enter:
</p>
<pre>
android create test-project -m &lt;main_path&gt; -n &lt;project_name&gt; -p &lt;test_path&gt;
</pre>
<p>
You must supply all the flags. The following table explains them in detail:
</p>
<table>
<tr>
<th>Flag</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td><code>-m, --main</code></td>
<td>
Path to the project of the application under test, relative to the test package
directory.
</td>
<td>
For example, if the application under test is in <code>source/HelloAndroid</code>, and
you want to create the test project in <code>source/HelloAndroidTest</code>, then the
value of <code>--main</code> should be <code>../HelloAndroid</code>.
<p>
To learn more about choosing the location of test projects, please read
<a href="{@docRoot}guide/topics/testing/testing_android.html#TestProjects">
Testing Fundamentals</a>.
</p>
</td>
</tr>
<tr>
<td><code>-n, --name</code></td>
<td>Name that you want to give the test project.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-p, --path</code></td>
<td>Directory in which you want to create the new test project.</td>
<td>
The <code>android</code> tool creates the test project files and directory structure
in this directory. If the directory does not exist, <code>android</code> creates it.
</td>
</tr>
</table>
<p>
If the operation is successful, <code>android</code> lists to STDOUT the names of the files
and directories it has created.
</p>
<p>
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
<a href="{@docRoot}guide/developing/other-ide.html">Developing In Other IDEs</a>.
</p>
<p>
The operation also creates an <code>AndroidManifest.xml</code> 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.
</p>
<p>
For example, suppose you create the <a href="{@docRoot}resources/tutorials/hello-world.html">
Hello, World</a> tutorial application in the directory <code>~/source/HelloAndroid</code>.
In the tutorial, this application uses the package name <code>com.example.helloandroid</code>
and the activity name <code>HelloAndroid</code>. You can to create the test for this in
<code>~/source/HelloAndroidTest</code>. To do so, you enter:
</p>
<pre>
$ cd ~/source
$ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAndroidTest
</pre>
<p>
This creates a directory called <code>~/src/HelloAndroidTest</code>. In the new directory you
see the file <code>AndroidManifest.xml</code>. This file contains the following
instrumentation-related elements and attributes:
</p>
<ul>
<li>
<code>&lt;application&gt;</code>: to contain the
<code>&lt;uses-library&gt;</code> element.
</li>
<li>
<code>&lt;uses-library android:name=&quot;android.test.runner&quot;</code>:
specifies this testing application uses the <code>android.test.runner</code> library.
</li>
<li>
<code>&lt;instrumentation&gt;</code>: contains attributes that control Android
instrumentation. The attributes are:
<ul>
<li>
<code>android:name=&quot;android.test.InstrumentationTestRunner&quot;</code>:
{@link android.test.InstrumentationTestRunner} runs test cases. It extends both
JUnit test case runner classes and Android instrumentation classes.
</li>
<li>
<code>android:targetPackage=&quot;com.example.helloandroid&quot;</code>: specifies
that the tests in HelloAndroidTest should be run against the application with the
<em>Android</em> package name <code>com.example.helloandroid</code>. This is the
package name of the <a
href="{@docRoot}resources/tutorials/hello-world.html">Hello, World</a>
tutorial application.
</li>
<li>
<code>android:label=&quot;Tests for .HelloAndroid&quot;</code>: specifies a
user-readable label for the instrumentation class. By default,
the <code>android</code> tool gives it the value &quot;Tests for &quot; plus
the name of the main Activity of the application under test.
</li>
</ul>
</li>
</ul>
<h3 id="UpdateTestProject">Updating a test project</h3>
<p>
You use the <code>android</code> tool when you need to change the path to the
project of the application under test. If you are changing an existing test project created in
Eclipse with ADT so that you can also build and run it from the command line, you must use the
"create" operation. See the section <a href="#CreateTestProject">Creating a test project</a>.
</p>
<p class="note">
<strong>Note:</strong> If you change the Android package name of the application under test,
you must <em>manually</em> change the value of the <code>&lt;android:targetPackage&gt;</code>
attribute within the <code>AndroidManifest.xml</code> file of the test package.
Running <code>android update test-project</code> does not do this.
</p>
<p>
To update a test project with the <code>android</code> tool, enter:
</p>
<pre>android update-test-project -m &lt;main_path&gt; -p &lt;test_path&gt;</pre>
<table>
<tr>
<th>Flag</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td><code>-m, --main</code></td>
<td>The path to the project of the application under test, relative to the test project</td>
<td>
For example, if the application under test is in <code>source/HelloAndroid</code>, and
the test project is in <code>source/HelloAndroidTest</code>, then the value for
<code>--main</code> is <code>../HelloAndroid</code>.
</td>
</tr>
<tr>
<td><code>-p, --path</code></td>
<td>The of the test project.</td>
<td>
For example, if the test project is in <code>source/HelloAndroidTest</code>, then the
value for <code>--path</code> is <code>HelloAndroidTest</code>.
</td>
</tr>
</table>
<p>
If the operation is successful, <code>android</code> lists to STDOUT the names of the files
and directories it has created.
</p>
<h2 id="CreateTestApp">Creating a Test Package</h2>
<p>
Once you have created a test project, you populate it with a test package.
The application does not require an {@link android.app.Activity Activity},
although you can define one if you wish. Although your test package 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.
</p>
<p>
If you run your tests with {@link android.test.InstrumentationTestRunner}
(or a related test runner), then it will run all the methods in each class. You can modify
this behavior by using the {@link junit.framework.TestSuite TestSuite} class.
</p>
<p>
To create a test package, start with one of Android's test classes in the Java package
{@link android.test android.test}. These extend the JUnit
{@link junit.framework.TestCase TestCase} class. With a few exceptions, the Android test
classes also provide instrumentation for testing.
</p>
<p>
For test classes that extend {@link junit.framework.TestCase TestCase}, you probably want to
override the <code>setUp()</code> and <code>tearDown()</code> methods:
</p>
<ul>
<li>
<code>setUp()</code>: 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 <code>setUp()</code>
to instantiate a new <code>Intent</code> object with the action <code>ACTION_MAIN</code>.
You can then use this intent to start the Activity under test.
<p class="note">
<strong>Note:</strong> If you override this method, call
<code>super.setUp()</code> as the first statement in your code.
</p>
</li>
<li>
<code>tearDown()</code>: 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.
<p class="note"><strong>Note:</strong> If you override this method, you must call
<code>super.tearDown()</code> as the <em>last</em> statement in your code.</p>
</li>
</ul>
<p>
Another useful convention is to add the method <code>testPreConditions()</code> 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.
</p>
<p>
To learn more about creating test packages, see the topic <a
href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>,
which provides an overview of Android testing. If you prefer to follow a tutorial,
try the <a href="{@docRoot}resources/tutorials/testing/activity_test.html">Activity Testing</a>
tutorial, which leads you through the creation of tests for an actual Android application.
</p>
<h2 id="RunTestsCommand">Running Tests</h2>
<p>
You run tests from the command line, either with Ant or with an
<a href="{@docRoot}guide/developing/tools/adb.html">
Android Debug Bridge (adb)</a> shell.
</p>
<h3 id="RunTestsAnt">Quick build and run with Ant</h3>
<p>
You can use Ant to run all the tests in your test project, using the target
<code>run-tests</code>, which is created automatically when you create a test project with
the <code>android</code> tool.
</p>
<p>
This target re-builds your main project and test project if necessary, installs the test
application to the current AVD or device, and then runs all the test classes in the test
application. The results are directed to <code>STDOUT</code>.
</p>
<p>
You can update an existing test project to use this feature. To do this, use the
<code>android</code> tool with the <code>update test-project</code> option. This is described
in the section <a href="#UpdateTestProject">Updating a test project</a>.
</p>
<h3 id="RunTestsDevice">Running tests on a device or emulator</h3>
<p>
When you run tests from the command line with
<a href="{@docRoot}guide/developing/tools/adb.html">
Android Debug Bridge (adb)</a>, you get more options for choosing the tests
to run than with any other method. You can select individual test methods, filter tests
according to their annotation, or specify testing options. Since the test run is controlled
entirely from a command line, you can customize your testing with shell scripts in various ways.
</p>
<p>
To run a test from the command line, you run <code>adb shell</code> to start a command-line
shell on your device or emulator, and then in the shell run the <code>am instrument</code>
command. You control <code>am</code> and your tests with command-line flags.
</p>
<p>
As a shortcut, you can start an <code>adb</code> shell, call <code>am instrument</code>, and
specify command-line flags all on one input line. The shell opens on the device or emulator,
runs your tests, produces output, and then returns to the command line on your computer.
</p>
<p>
To run a test with <code>am instrument</code>:
</p>
<ol>
<li>
If necessary, rebuild your main application and test package.
</li>
<li>
Install your test package and main application Android package files
(<code>.apk</code> files) to your current Android device or emulator</li>
<li>
At the command line, enter:
<pre>
$ adb shell am instrument -w &lt;test_package_name&gt;/&lt;runner_class&gt;
</pre>
<p>
where <code>&lt;test_package_name&gt;</code> is the Android package name of your test
application, and <code>&lt;runner_class&gt;</code> is the name of the Android test
runner class you are using. The Android package name is the value of the
<code>package</code> attribute of the <code>manifest</code> element in the manifest file
(<code>AndroidManifest.xml</code>) of your test package. The Android test runner
class is usually {@link android.test.InstrumentationTestRunner}.
</p>
<p>
Your test results appear in <code>STDOUT</code>.
</p>
</li>
</ol>
<p>
This operation starts an <code>adb</code> shell, then runs <code>am instrument</code>
with the specified parameters. This particular form of the command will run all of the tests
in your test package. You can control this behavior with flags that you pass to
<code>am instrument</code>. These flags are described in the next section.
</p>
<h2 id="AMSyntax">Using the am instrument Command</h2>
<p>
The general syntax of the <code>am instrument</code> command is:
</p>
<pre>
am instrument [flags] &lt;test_package&gt;/&lt;runner_class&gt;
</pre>
<p>
The main input parameters to <code>am instrument</code> are described in the following table:
</p>
<table>
<tr>
<th>
Parameter
</th>
<th>
Value
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
<code>&lt;test_package&gt;</code>
</td>
<td>
The Android package name of the test package.
</td>
<td>
The value of the <code>package</code> attribute of the <code>manifest</code>
element in the test package's manifest file.
</td>
</tr>
<tr>
<td>
<code>&lt;runner_class&gt;</code>
</td>
<td>
The class name of the instrumented test runner you are using.
</td>
<td>
This is usually {@link android.test.InstrumentationTestRunner}.
</td>
</tr>
</table>
<p>
The flags for <code>am instrument</code> are described in the following table:
</p>
<table>
<tr>
<th>
Flag
</th>
<th>
Value
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
<code>-w</code>
</td>
<td>
(none)
</td>
<td>
Forces <code>am instrument</code> to wait until the instrumentation terminates
before terminating itself. The net effect is to keep the shell open until the tests
have finished. This flag is not required, but if you do not use it, you will not
see the results of your tests.
</td>
</tr>
<tr>
<td>
<code>-r</code>
</td>
<td>
(none)
</td>
<td>
Outputs results in raw format. Use this flag when you want to collect
performance measurements, so that they are not formatted as test results. This flag is
designed for use with the flag <code>-e perf true</code> (documented in the section
<a href="#AMOptionsSyntax">Instrument options</a>).
</td>
</tr>
<tr>
<td>
<code>-e</code>
</td>
<td>
&lt;test_options&gt;
</td>
<td>
Provides testing options as key-value pairs. The
<code>am instrument</code> tool passes these to the specified instrumentation class
via its <code>onCreate()</code> method. You can specify multiple occurrences of
<code>-e &lt;test_options&gt;</code>. The keys and values are described in the
section <a href="#AMOptionsSyntax">am instrument options</a>.
<p>
The only instrumentation class that uses these key-value pairs is
{@link android.test.InstrumentationTestRunner} (or a subclass). Using them with
any other class has no effect.
</p>
</td>
</tr>
</table>
<h3 id="AMOptionsSyntax">am instrument options</h3>
<p>
The <code>am instrument</code> tool passes testing options to
<code>InstrumentationTestRunner</code> or a subclass in the form of key-value pairs,
using the <code>-e</code> flag, with this syntax:
</p>
<pre>
-e &lt;key&gt; &lt;value&gt;
</pre>
<p>
Some keys accept multiple values. You specify multiple values in a comma-separated list.
For example, this invocation of <code>InstrumentationTestRunner</code> provides multiple
values for the <code>package</code> key:
</p>
<pre>
$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
&gt; com.android.test/android.test.InstrumentationTestRunner
</pre>
<p>
The following table describes the key-value pairs and their result. Please review the
<strong>Usage Notes</strong> following the table.
</p>
<table>
<tr>
<th>Key</th>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>
<code>package</code>
</td>
<td>
&lt;Java_package_name&gt;
</td>
<td>
The fully-qualified <em>Java</em> package name for one of the packages in the test
application. Any test case class that uses this package name is executed. Notice that
this is not an <em>Android</em> package name; a test package has a single
Android package name but may have several Java packages within it.
</td>
</tr>
<tr>
<td rowspan="2"><code>class</code></td>
<td>&lt;class_name&gt;</td>
<td>
The fully-qualified Java class name for one of the test case classes. Only this test
case class is executed.
</td>
</tr>
<tr>
<td>&lt;class_name&gt;<strong>#</strong>method name</td>
<td>
A fully-qualified test case class name, and one of its methods. Only this method is
executed. Note the hash mark (#) between the class name and the method name.
</td>
</tr>
<tr>
<td><code>func</code></td>
<td><code>true</code></td>
<td>
Runs all test classes that extend {@link android.test.InstrumentationTestCase}.
</td>
</tr>
<tr>
<td><code>unit</code></td>
<td><code>true</code></td>
<td>
Runs all test classes that do <em>not</em> extend either
{@link android.test.InstrumentationTestCase} or
{@link android.test.PerformanceTestCase}.
</td>
</tr>
<tr>
<td><code>size</code></td>
<td>
[<code>small</code> | <code>medium</code> | <code>large</code>]
</td>
<td>
Runs a test method annotated by size. The annotations are <code>@SmallTest</code>,
<code>@MediumTest</code>, and <code>@LargeTest</code>.
</td>
</tr>
<tr>
<td><code>perf</code></td>
<td><code>true</code></td>
<td>
Runs all test classes that implement {@link android.test.PerformanceTestCase}.
When you use this option, also specify the <code>-r</code> flag for
<code>am instrument</code>, so that the output is kept in raw format and not
re-formatted as test results.
</td>
</tr>
<tr>
<td><code>debug</code></td>
<td><code>true</code></td>
<td>
Runs tests in debug mode.
</td>
</tr>
<tr>
<td><code>log</code></td>
<td><code>true</code></td>
<td>
Loads and logs all specified tests, but does not run them. The test
information appears in <code>STDOUT</code>. Use this to verify combinations of other
filters and test specifications.
</td>
</tr>
<tr>
<td><code>emma</code></td>
<td><code>true</code></td>
<td>
Runs an EMMA code coverage analysis and writes the output to
<code>/data//coverage.ec</code> on the device. To override the file location, use the
<code>coverageFile</code> key that is described in the following entry.
<p class="note">
<strong>Note:</strong> This option requires an EMMA-instrumented build of the test
application, which you can generate with the <code>coverage</code> target.
</p>
</td>
</tr>
<tr>
<td><code>coverageFile</code></td>
<td><code>&lt;filename&gt;</code></td>
<td>
Overrides the default location of the EMMA coverage file on the device. Specify this
value as a path and filename in UNIX format. The default filename is described in the
entry for the <code>emma</code> key.
</td>
</tr>
</table>
<strong><code>-e</code> Flag Usage Notes</strong>
<ul>
<li>
<code>am instrument</code> invokes
{@link android.test.InstrumentationTestRunner#onCreate(Bundle)}
with a {@link android.os.Bundle} containing the key-value pairs.
</li>
<li>
The <code>package</code> key takes precedence over the <code>class</code> key. If you
specifiy a package, and then separately specify a class within that package, Android
will run all the tests in the package and ignore the <code>class</code> key.
</li>
<li>
The <code>func</code> key and <code>unit</code> key are mutually exclusive.
</li>
</ul>
<h3 id="RunTestExamples">Usage examples</h3>
<p>
The following sections provide examples of using <code>am instrument</code> to run tests.
They are based on the following structure:</p>
<ul>
<li>
The test package has the Android package name <code>com.android.demo.app.tests</code>
</li>
<li>
There are three test classes:
<ul>
<li>
<code>UnitTests</code>, which contains the methods
<code>testPermissions</code> and <code>testSaveState</code>.
</li>
<li>
<code>FunctionTests</code>, which contains the methods
<code>testCamera</code>, <code>testXVGA</code>, and <code>testHardKeyboard</code>.
</li>
<li>
<code>IntegrationTests</code>,
which contains the method <code>testActivityProvider</code>.
</li>
</ul>
</li>
<li>
The test runner is {@link android.test.InstrumentationTestRunner}.
</li>
</ul>
<h4>Running the entire test package</h4>
<p>
To run all of the test classes in the test package, enter:
</p>
<pre>
$ adb shell am instrument -w com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre>
<h4>Running all tests in a test case class</h4>
<p>
To run all of the tests in the class <code>UnitTests</code>, enter:
</p>
<pre>
$ adb shell am instrument -w \
&gt; -e class com.android.demo.app.tests.UnitTests \
&gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre>
<p>
<code>am instrument</code> gets the value of the <code>-e</code> flag, detects the
<code>class</code> keyword, and runs all the methods in the <code>UnitTests</code> class.
</p>
<h4>Selecting a subset of tests</h4>
<p>
To run all of the tests in <code>UnitTests</code>, and the <code>testCamera</code> method in
<code>FunctionTests</code>, enter:
</p>
<pre>
$ adb shell am instrument -w \
&gt; -e class com.android.demo.app.tests.UnitTests,com.android.demo.app.tests.FunctionTests#testCamera \
&gt; com.android.demo.app.tests/android.test.InstrumentationTestRunner
</pre>
<p>
You can find more examples of the command in the documentation for
{@link android.test.InstrumentationTestRunner}.
</p>
base/docs/html/guide/developing/tools/MonkeyDevice.jd
+1353
View File
File diff suppressed because it is too large Load Diff
base/docs/html/guide/developing/tools/MonkeyImage.jd
+435
View File
@@ -0,0 +1,435 @@
page.title=MonkeyImage
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class to hold an image of the device or emulator's screen. The image is
copied from the screen buffer during a screenshot. This object's methods allow you to
convert the image into various storage formats, write the image to a file, copy parts of
the image, and compare this object to other <code>MonkeyImage</code> objects.
</p>
<p>
You do not need to create new instances of <code>MonkeyImage</code>. Instead, use
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html#takeSnapshot">
MonkeyDevice.takeSnapshot()</a></code> to create a new instance from a screenshot. For example, use:
</p>
<pre>
newimage = MonkeyDevice.takeSnapshot()
</pre>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#convertToBytes">convertToBytes</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Converts the current image to a particular format and returns it as a
<em>string</em> that you can then access as an <em>iterable</em> of binary bytes.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>tuple</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixel">getRawPixel</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixelInt">getRawPixelInt</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as
a 32-bit <em>integer</em>.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getSubImage">getSubImage</a>
</span>
(<em>tuple</em> rect)
</nobr>
<div class="jd-descrdiv">
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>boolean</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sameAs">sameAs</a>
</span>
(<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>
other,
<em>float</em> percent)
</nobr>
<div class="jd-descrdiv">
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>void</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#writeToFile">writeToFile</a>
</span>
(<em>string</em> path,
<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="convertToBytes"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">convertToBytes</span>
<span class="normal">
(
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Converts the current image to a particular format and returns it as a <em>string</em>
that you can then access as an <em>iterable</em> of binary bytes.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The desired output format. All of the common raster output formats are supported.
The default value is "png" (Portable Network Graphics).
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="getRawPixel"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixel</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A tuple of integers representing the pixel, in the form (a,r,g,b) where
a is the alpha channel value, and r, g, and b are the red, green, and blue values,
respectively.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getRawPixelInt"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixelInt</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
an <em>integer</em>. Use this method to economize on memory.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit
integer, with a as the leftmost 8 bits, r the next rightmost, and so forth.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getSubImage"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code>
</span>
<span class="sympad">getSubImage</span>
<span class="normal">
(<em>tuple</em> rect)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>rect</th>
<td>
A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel
position of the upper left-hand corner of the selection. w specifies the width of the
region, and h specifies its height, both in units of pixels.
<p>
The image's orientation is the same as the screen orientation at the time the
screenshot was made.
</p>
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A new <code>MonkeyImage</code> object containing the selection.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sameAs"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>boolean</em>
</span>
<span class="sympad">sameAs</span>
<span class="normal">
(
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code> otherImage,
<em>float</em> percent
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>other</th>
<td>
Another <code>MonkeyImage</code> object to compare to this one.
</td>
</tr>
<tr>
<th>
percent
</th>
<td>
A float in the range 0.0 to 1.0, inclusive, indicating
the percentage of pixels that need to be the same for the method to return
<code>true</code>. The default is 1.0, indicating that all the pixels
must match.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
Boolean <code>true</code> if the images match, or boolean <code>false</code> otherwise.
</li>
</ul>
</div>
</div>
</div>
<A NAME="writeToFile"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">writeToFile</span>
<span class="normal">
(<em>string</em> filename,
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>path</th>
<td>
The fully-qualified filename and extension of the output file.
</td>
</tr>
<tr>
<th>
format
</th>
<td>
The output format to use for the file. If no format is provided, then the
method tries to guess the format from the filename's extension. If no
extension is provided and no format is specified, then the default format of
"png" (Portable Network Graphics) is used.
</td>
</tr>
</table>
</div>
</div>
</div>
base/docs/html/guide/developing/tools/MonkeyRunner.jd
+445
View File
@@ -0,0 +1,445 @@
page.title=MonkeyRunner
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class that contains static utility methods.
</p>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#alert">alert</a>
</span>
(<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</nobr>
<div class="jd-descrdiv">
Displays an alert dialog to the process running the current
program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#choice">choice</a>
</span>
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</nobr>
<div class="jd-descrdiv">
Displays a dialog with a list of choices to the process running the current program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#help">help</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#input">input</a>
</span>
(<em>string</em> message,
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</nobr>
<div class="jd-descrdiv">
Displays a dialog that accepts input.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sleep">sleep</a>
</span>
(<em>float</em> seconds)
</nobr>
<div class="jd-descrdiv">
Pauses the current program for the specified number of seconds.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#waitForConnection">waitForConnection</a>
</span>
(<em>float</em> timeout,
<em>string</em> deviceId)
</nobr>
<div class="jd-descrdiv">
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="alert"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">alert</span>
<span class="normal">
(
<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays an alert dialog to the process running the current
program. The dialog is modal, so the program pauses until the user clicks the dialog's
button.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The message to display in the dialog.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default value is "Alert".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the dialog button. The default value is "OK".
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="choice"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>integer</em>
</span>
<span class="sympad">choice</span>
<span class="normal">
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog with a list of choices to the process running the current program. The
dialog is modal, so the program pauses until the user clicks one of the dialog's
buttons.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>choices</th>
<td>
A Python iterable containing one or more objects that are displayed as strings. The
recommended form is an array of strings.
</td>
</tr>
<tr>
<th>
title
</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user makes a selection and clicks the "OK" button, the method returns
the 0-based index of the selection within the iterable.
If the user clicks the "Cancel" button, the method returns -1.
</li>
</ul>
</div>
</div>
</div>
<A NAME="help"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">help</span>
<span class="normal">
(<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The markup format to use in the output. The possible values are "text" for plain text
or "html" for HTML.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="input"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">input</span>
<span class="normal">
(<em>string</em> message
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog that accepts input and returns it to the program. The dialog is
modal, so the program pauses until the user clicks one of the dialog's buttons.
</p>
<p>
The dialog contains two buttons, one of which displays the okTitle value
and the other the cancelTitle value. If the user clicks the okTitle button,
the current value of the input box is returned. If the user clicks the cancelTitle
button, an empty string is returned.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>initialValue</th>
<td>
The initial value to display in the dialog. The default is an empty string.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the okTitle button. The default is "OK".
</td>
</tr>
<tr>
<th>cancelTitle</th>
<td>
The text displayed in the cancelTitle button. The default is "Cancel".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user clicks the okTitle button, then the method returns the current value of
the dialog's input box. If the user clicks the cancelTitle button, the method returns
an empty string.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sleep"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">sleep</span>
<span class="normal">
(
<em>float</em> seconds
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Pauses the current program for the specified number of seconds.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>seconds</th>
<td>
The number of seconds to pause.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="waitForConnection"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a>
</code>
</span>
<span class="sympad">waitForConnection</span>
<span class="normal">
(<em>float</em> timeout,
<em>string</em> deviceId)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>timeout</th>
<td>
The number of seconds to wait for a connection. The default is to wait forever.
</td>
</tr>
<tr>
<th>
deviceId
</th>
<td>
A regular expression that specifies the serial number of the device or emulator. See
the topic
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
for a description of device and emulator serial numbers.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>
instance for the device or emulator. Use this object to control and communicate with the
device or emulator.
</li>
</ul>
</div>
</div>
</div>
base/docs/html/guide/developing/tools/aapt.jd
+20
View File
@@ -0,0 +1,20 @@
page.title=Using aapt
@jd:body
<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets.
</p>
<p>
Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application.
</p>
<p>
For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command:
</p>
<ul>
<li><p>Linux or Mac OS X:</p>
<pre>./aapt</pre>
</li>
<li><p>Windows:</p>
<pre>aapt.exe</pre>
</li>
</ul>
base/docs/html/guide/developing/tools/adb.jd
+701
View File
@@ -0,0 +1,701 @@
page.title=Android Debug Bridge
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>ADB quickview</h2>
<ul>
<li>Manage the state of an emulator or device</li>
<li>Run shell commands on a device</li>
<li>Manage port forwarding on an emulator or device</li>
<li>Copy files to/from an emulator or device</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#issuingcommands">Issuing ADB Commands</a></li>
<li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li>
<li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li>
<li><a href="#move">Installing an Application</a></li>
<li><a href="#forwardports">Forwarding Ports</a></li>
<li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li>
<li><a href="#commandsummary">Listing of adb Commands </a></li>
<li><a href="#shellcommands">Issuing Shell Commands</a></li>
<li><a href="#logcat">Enabling logcat Logging</a></li>
<li><a href="#stopping">Stopping the adb Server</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="emulator.html">Emulator</a></li>
</ol>
</div>
</div>
<!--
<p>Android Debug Bridge (adb) is a versatile tool that </a>. </p>
<p>Some of ways you can use adb include:</p>
<ul>
</ul>
<p>The sections below introduce adb and describe many of its common uses. </p>
<h2>Contents</h2>
<dl>
<dt><a href="#overview">Overview</a></dt>
<dt><a href="#issuingcommands">Issuing adb Commands</a></dt>
<dt><a href="#devicestatus">Querying for Emulator/Device Instances</a></dt>
<dt><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></dt>
<dt><a href="#move">Installing an Application</a></dt>
<dt><a href="#forwardports">Forwarding Ports</a></dt>
<dt><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></dt>
<dt><a href="#commandsummary">Listing of adb Commands </a></dt>
<dt><a href="#shellcommands">Issuing Shell Commands</a></dt>
<dd><a href="#sqlite">Examining sqlite3 Databases from a Remote Shell</a></dd>
<dd><a href="#monkey">UI/Application Exerciser Monkey</a></dd>
<dd><a href="#othershellcommands">Other Shell Commands</a></dd>
<dt><a href="#logcat">Enabling logcat Logging</a> </dt>
<dd><a href="#usinglogcat">Using logcat Commands</a></dd>
<dd><a href="#filteringoutput">Filtering Log Output</a></dd>
<dd><a href="#outputformat">Controlling Log Output Format</a></dd>
<dd><a href="#alternativebuffers">Viewing Alternative Log Buffers</a></dd>
<dd><a href="#stdout">Viewing stdout and stderr</a></dd>
<dd><a href="#logcatoptions">Listing of logcat Command Options</a></dd>
<dt><a href="#stopping">Stopping the adb Server</a> </dt>
</dl>
<a name="overview"></a>
<h2>Overview</h2>
-->
<p>Android Debug Bridge (adb) is a versatile tool lets you manage the state of an emulator instance or Android-powered device. It is a client-server program that includes three components: </p>
<ul>
<li>A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create adb clients. </li>
<li>A server, which runs as a background process on your development machine. The server manages communication between the client and the adb daemon running on an emulator or device. </li>
<li>A daemon, which runs as a background process on each emulator or device instance. </li>
</ul>
<p>You can find the {@code adb} tool in {@code &lt;sdk&gt;/platform-tools/}.</p>
<p>When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients&mdash;all adb clients use port 5037 to communicate with the adb server. </p>
<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports &mdash; an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p>
<p style="margin-left:2em">
Emulator 1, console: 5554<br/>
Emulator 1, adb: 5555<br>
Emulator 2, console: 5556<br>
Emulator 2, adb: 5557 ...
</p>
<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p>
<p>Once the server has set up connections to all emulator instances, you can use adb commands to control and access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).</p>
<p>The sections below describe the commands that you can use to access adb capabilities and manage the state of an emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you do not need to access adb from the command line. The ADT plugin provides a transparent integration of adb into the Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.</p>
<a name="issuingcommands"></a>
<h2>Issuing adb Commands</h2>
<p>You can issue adb commands from a command line on your development machine or from a script. The usage is: </p>
<pre>adb [-d|-e|-s &lt;serialNumber&gt;] &lt;command&gt; </pre>
<p>When you issue a command, the program invokes an adb client. The client is not specifically associated with any emulator instance, so if multiple emulators/devices are running, you need to use the <code>-d</code> option to specify the target instance to which the command should be directed. For more information about using this option, see <a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a>. </p>
<a name="devicestatus"></a>
<h2>Querying for Emulator/Device Instances</h2>
<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p>
<pre>adb devices</pre>
<p>In response, adb prints this status information for each instance:</p>
<ul>
<li>Serial number &mdash; A string created by adb to uniquely identify an emulator/device instance by its
console port number. The format of the serial number is <code>&lt;type&gt;-&lt;consolePort&gt;</code>.
Here's an example serial number: <code>emulator-5554</code></li>
<li>State &mdash; The connection state of the instance. Three states are supported:
<ul>
<li><code>offline</code> &mdash; the instance is not connected to adb or is not responding.</li>
<li><code>device</code> &mdash; the instance is now connected to the adb server. Note that this state does not
imply that the Android system is fully booted and operational, since the instance connects to adb
while the system is still booting. However, after boot-up, this is the normal operational state of
an emulator/device instance.</li>
</ul>
</li>
</ul>
<p>The output for each instance is formatted like this: </p>
<pre>[serialNumber] [state]</pre>
<p>Here's an example showing the <code>devices</code> command and its output:</p>
<pre>$ adb devices
List of devices attached
emulator-5554&nbsp;&nbsp;device
emulator-5556&nbsp;&nbsp;device
emulator-5558&nbsp;&nbsp;device</pre>
<p>If there is no emulator/device running, adb returns <code>no device</code>.</p>
<a name="directingcommands"></a>
<h2>Directing Commands to a Specific Emulator/Device Instance</h2>
<p>If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands. To so so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p>
<pre>adb -s &lt;serialNumber&gt; &lt;command&gt; </pre>
<p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. </p>
<p>Here is an example: </p>
<pre>adb -s emulator-5556 install helloWorld.apk</pre>
<p>Note that, if you issue a command without specifying a target emulator/device instance using <code>-s</code>, adb generates an error.
<a name="move"></a>
<h2>Installing an Application</h2>
<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p>
<pre>adb install &lt;path_to_apk&gt;</pre>
<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a> (aapt). </p>
<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p>
<a name="forwardports"></a>
<h2>Forwarding Ports</h2>
<p>You can use the <code>forward</code> command to set up arbitrary port forwarding &mdash; forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p>
<pre>adb forward tcp:6100 tcp:7100</pre>
<p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p>
<pre>adb forward tcp:6100 local:logd </pre>
<a name="copyfiles"></a>
<h2>Copying Files to or from an Emulator/Device Instance</h2>
<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to and from an emulator/device instance's data file. Unlike the <code>install</code> command, which only copies an .apk file to a specific location, the <code>pull</code> and <code>push</code> commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p>
<p>To copy a file or directory (recursively) <em>from</em> the emulator or device, use</p>
<pre>adb pull &lt;remote&gt; &lt;local&gt;</pre>
<p>To copy a file or directory (recursively) <em>to</em> the emulator or device, use</p>
<pre>adb push &lt;local&gt; &lt;remote&gt;</pre>
<p>In the commands, <code>&lt;local&gt;</code> and <code>&lt;remote&gt;</code> refer to the paths to the target files/directory on your development machine (local) and on the emulator/device instance (remote).</p>
<p>Here's an example: </p>
<pre>adb push foo.txt /sdcard/foo.txt</pre>
<a name="commandsummary"></a>
<h2>Listing of adb Commands</h2>
<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p>
<table>
<tr>
<th>Category</th>
<th>Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="3">Options</td>
<td><code>-d</code></td>
<td>Direct an adb command to the only attached USB device.</td>
<td>Returns an error if more than one USB device is attached.</td>
</tr>
<tr>
<td><code>-e</code></td>
<td>Direct an adb command to the only running emulator instance.</td>
<td>Returns an error if more than one emulator instance is running. </td>
</tr>
<tr>
<td><code>-s&nbsp;&lt;serialNumber&gt;</code></td>
<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td>
<td>If not specified, adb generates an error.</td>
</tr>
<tr>
<td rowspan="3">General</td>
<td><code>devices</code></td>
<td>Prints a list of all attached emulator/device instances.</td>
<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td>
</tr>
<tr>
<td><code>help</code></td>
<td>Prints a list of supported adb commands.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>version</code></td>
<td>Prints the adb version number. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="3">Debug</td>
<td ><code>logcat&nbsp;[&lt;option&gt;] [&lt;filter-specs&gt;]</code></td>
<td>Prints log data to the screen. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>bugreport</code></td>
<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>jdwp</code></td>
<td>Prints a list of available JDWP processes on a given device. </td>
<td>You can use the <code>forward jdwp:&lt;pid&gt;</code> port-forwarding specification to connect to a specific JDWP process. For example: <br>
<code>adb forward tcp:8000 jdwp:472</code><br>
<code>jdb -attach localhost:8000</code></p>
</td>
</tr>
<tr>
<td rowspan=3">Data</td>
<td><code>install&nbsp;&lt;path-to-apk&gt;</code></td>
<td>Pushes an Android application (specified as a full path to an .apk file) to the data file of an emulator/device. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>pull&nbsp;&lt;remote&gt;&nbsp;&lt;local&gt;</code></td>
<td>Copies a specified file from an emulator/device instance to your development computer. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>push&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Copies a specified file from your development computer to an emulator/device instance. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Ports and Networking</td>
<td><code>forward&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td>
<td>Port specifications can use these schemes:
<ul><li><code>tcp:&lt;portnum&gt;</code></li>
<li><code>local:&lt;UNIX domain socket name&gt;</code></li>
<li><code>dev:&lt;character device name&gt;</code></li>
<li><code>jdwp:&lt;pid&gt;</code></li></ul>
</td>
</tr>
<tr>
<td><code>ppp&nbsp;&lt;tty&gt;&nbsp;[parm]...</code></td>
<td>Run PPP over USB.
<ul>
<li><code>&lt;tty&gt;</code> &mdash; the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li>
<li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul>
<p>Note that you should not automatically start a PPP connection. </p></td>
<td></td>
</tr>
<tr>
<td rowspan="3">Scripting</td>
<td><code>get-serialno</code></td>
<td>Prints the adb instance serial number string.</td>
<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td>
</tr>
<tr>
<td><code>get-state</code></td>
<td>Prints the adb state of an emulator/device instance.</td>
</td>
</tr>
<tr>
<td><code>wait-for-device</code></td>
<td>Blocks execution until the device is online &mdash; that is, until the instance state is <code>device</code>.</td>
<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
<pre>adb wait-for-device shell getprop</pre>
Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as
<pre>adb wait-for-device install &lt;app&gt;.apk</pre>
would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td>
</tr>
<tr>
<td rowspan="2">Server</td>
<td><code>start-server</code></td>
<td>Checks whether the adb server process is running and starts it, if not.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>kill-server</code></td>
<td>Terminates the adb server process.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Shell</td>
<td><code>shell</code></td>
<td>Starts a remote shell in the target emulator/device instance.</td>
<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td>
</tr>
<tr>
<td><code>shell&nbsp;[&lt;shellCommand&gt;]</code></td>
<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td>
</tr>
</table>
<a name="shellcommands"></a>
<h2>Issuing Shell Commands</h2>
<p>Adb provides an ash shell that you can use to run a variety of commands on an emulator
or device. The command binaries are stored in the file system of the emulator or device,
in this location: </p>
<pre>/system/bin/...</pre>
<p>You can use the <code>shell</code> command to issue commands, with or without entering the adb remote shell on the emulator/device. </p>
<p>To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p>
<pre>adb [-d|-e|-s {&lt;serialNumber&gt;}] shell &lt;shellCommand&gt;</pre>
<p>To drop into a remote shell on a emulator/device instance, use the <code>shell</code> command like this:</p>
<pre>adb [-d|-e|-s {&lt;serialNumber&gt;}] shell</pre>
<p>When you are ready to exit the remote shell, use <code>CTRL+D</code> or <code>exit</code> to end the shell session. </p>
<p>The sections below provide more information about shell commands that you can use.</p>
<a name="sqlite" id="sqlite"></a>
<h3>Examining sqlite3 Databases from a Remote Shell</h3>
<p>From an adb remote shell, you can use the
<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to
manage SQLite databases created by Android applications. The
<code>sqlite3</code> tool includes many useful commands, such as
<code>.dump</code> to print out the contents of a table and
<code>.schema</code> to print the SQL CREATE statement for an existing table.
The tool also gives you the ability to execute SQLite commands on the fly.</p>
<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em>&lt;package_name&gt;</em>/databases</span></span>/</code>. </p>
<p>Here's an example: </p>
<pre>$ adb -s emulator-5554 shell
# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
SQLite version 3.3.12
Enter &quot;.help&quot; for instructions
<em>.... enter commands, then quit...</em>
sqlite&gt; .exit </pre>
<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>.
<a name="monkey"></a>
<h3>UI/Application Exerciser Monkey</h3>
<p>The Monkey is a program that runs on your emulator or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-level
events. You can use the Monkey to stress-test applications that you are developing,
in a random yet repeatable manner.</p>
<p>The simplest way to use the monkey is with the following command, which will launch your
application and send 500 pseudo-random events to it.</p>
<pre>$ adb shell monkey -v -p your.package.name 500</pre>
<p>For more information about command options for Monkey, see the complete
<a href="{@docRoot}guide/developing/tools/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p>
<a name="othershellcommands"></a>
<h3>Other Shell Commands</h3>
<p>The table below lists several of the adb shell commands available. For a complete list of commands and programs, start an emulator instance and use the <code>adb -help</code> command. </p>
<pre>adb shell ls /system/bin</pre>
<p>Help is available for most of the commands. </p>
<table>
<tr>
<th>Shell Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>dumpsys</code></td>
<td>Dumps system data to the screen.</td>
<td rowspan=4">The <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td>
</tr>
<tr>
<td><code>dumpstate</code></td>
<td>Dumps state to a file.</td>
</tr>
<tr>
<td><code>logcat&nbsp;[&lt;option&gt;]...&nbsp;[&lt;filter-spec&gt;]...</code></td>
<td>Enables radio logging and prints output to the screen. </td>
</tr>
<tr>
<td><code>dmesg</code></td>
<td>Prints kernel debugging messages to the screen. </td>
</tr>
<tr>
<td><code>start</code></td>
<td>Starts (restarts) an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>stop</code></td>
<td>Stops execution of an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
</table>
<a name="logcat"></a>
<h2>Enabling logcat Logging</h2>
<p>The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the <code>logcat</code> command.</p>
<a name="usinglogcat"></a>
<h3>Using logcat Commands</h3>
<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p>
<pre>[adb] logcat [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...</pre>
<p>The sections below explain filter specifications and the command options. See <a href="#logcatoptions">Listing of logcat Command Options</a> for a summary of options. </p>
<p>You can use the <code>logcat</code> command from your development computer or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use</p>
<pre>$ adb logcat</pre>
<p>and from a remote adb shell you use</p>
<pre># logcat</pre>
<a name="filteringoutput"></a>
<h3>Filtering Log Output</h3>
<p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it. </p>
<ul>
<li>The tag of a log message is a short string indicating the system component from which the message originates (for example, "View" for the view system). </li>
<li>The priority is one of the following character values, ordered from lowest to highest priority:</li>
<ul>
<li><code>V</code> &mdash; Verbose (lowest priority)</li>
<li><code>D</code> &mdash; Debug</li>
<li><code>I</code> &mdash; Info</li>
<li><code>W</code> &mdash; Warning</li>
<li><code>E</code> &mdash; Error</li>
<li><code>F</code> &mdash; Fatal</li>
<li><code>S</code> &mdash; Silent (highest priority, on which nothing is ever printed)</li>
</ul>
</ul>
<p>You can obtain a list of tags used in the system, together with priorities, by running <code>logcat</code> and observing the first two columns
of each message, given as <code>&lt;priority&gt;/&lt;tag&gt;</code>. </p>
<p>Here's an example of logcat output that shows that the message relates to priority level "I" and tag "ActivityManager":</p>
<pre>I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}</pre>
<p>To reduce the log output to a manageable level, you can restrict log output using <em>filter expressions</em>. Filter expressions let you indicate to the system the tags-priority combinations that you are interested in &mdash; the system suppresses other messages for the specified tags. </p>
<p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of priority to report for that tag. Messages for that tag at or above the specified priority are written to the log. You can supply any number of <code>tag:priority</code> specifications in a single filter expression. The series of specifications is whitespace-delimited. </p>
<p>Here's an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", with priority "Debug" or above:</p>
<pre>adb logcat ActivityManager:I MyApp:D *:S</pre>
<p>The final element in the above expression, <code>*:S</code>, sets the priority level for all tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that you have explicitly specified &mdash; it lets your filters serve as a "whitelist" for log output.</p>
<p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p>
<pre>adb logcat *:W</pre>
<p>If you're running <code>logcat</code> from your development computer (versus running it on a remote adb shell), you can also set a default filter expression by exporting a value for the environment variable <code>ANDROID_LOG_TAGS</code>:</p>
<pre>export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"</pre>
<p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device instance, if you are running <code>logcat</code> from a remote shell or using <code>adb shell logcat</code>.</p>
<a name="outputformat"></a>
<h3>Controlling Log Output Format</h3>
<p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, you use the <code>-v</code> option and specify one of the supported output formats listed below. </p>
<ul>
<li><code>brief</code> &mdash; Display priority/tag and PID of originating process (the default format).</li>
<li><code>process</code> &mdash; Display PID only.</li>
<li><code>tag</code> &mdash; Display the priority/tag only. </li>
<li><code>thread</code> &mdash; Display process:thread and priority/tag only. </li>
<li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
<li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the originating process.</li>
<li><code>long</code> &mdash; Display all metadata fields and separate messages with a blank lines.</li>
</ul>
<p>When starting <code>logcat</code>, you can specify the output format you want by using the <code>-v</code> option:</p>
<pre>[adb] logcat [-v &lt;format&gt;]</pre>
<p>Here's an example that shows how to generate messages in <code>thread</code> output format: </p>
<pre>adb logcat -v thread</pre>
<p>Note that you can only specify one output format with the <code>-v</code> option. </p>
<a name="alternativebuffers"></a>
<h3>Viewing Alternative Log Buffers </h3>
<p>The Android logging system keeps multiple circular buffers for log messages, and not all of the log messages are sent to the default circular buffer. To see additional log messages, you can start <code>logcat</code> with the <code>-b</code> option, to request viewing of an alternate circular buffer. You can view any of these alternate buffers: </p>
<ul>
<li><code>radio</code> &mdash; View the buffer that contains radio/telephony related messages.</li>
<li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
<li><code>main</code> &mdash; View the main log buffer (default)</li>
</ul>
<p>The usage of the <code>-b</code> option is:</p>
<pre>[adb] logcat [-b &lt;buffer&gt;]</pre>
<p>Here's an example of how to view a log buffer containing radio and telephony messages: </p>
<pre>adb logcat -b radio</b></pre>
<a name="stdout"></a>
<h3>Viewing stdout and stderr</h3>
<p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In
processes that run the Dalvik VM, you can have the system write a copy of the output to the log file. In this case, the system writes the messages to the log using the log tags <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>. </p>
<p>To route the output in this way, you stop a running emulator/device instance and then use the shell command <code>setprop</code> to enable the redirection of output. Here's how you do it: </p>
<pre>$ adb shell stop
$ adb shell setprop log.redirect-stdio true
$ adb shell start</pre>
<p>The system retains this setting until you terminate the emulator/device instance. To use the setting as a default on the emulator/device instance, you can add an entry to <code>/data/local.prop</code>
on the device.</p>
<a name="logcatoptions"></a>
<h3>Listing of logcat Command Options</h3>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-b&nbsp;&lt;buffer&gt;</code></td>
<td>Loads an alternate log buffer for viewing, such as <code>event</code> or <code>radio</code>. The <code>main</code> buffer is used by default. See <a href="#alternativebuffers">Viewing Alternative Log Buffers</a>.</td>
</tr>
<tr>
<td><code>-c</code></td>
<td>Clears (flushes) the entire log and exits. </td>
</tr>
<tr>
<td><code>-d</code></td>
<td>Dumps the log to the screen and exits.</td>
</tr>
<tr>
<td><code>-f&nbsp;&lt;filename&gt;</code></td>
<td>Writes log message output to <code>&lt;filename&gt;</code>. The default is <code>stdout</code>.</td>
</tr>
<tr>
<td><code>-g</code></td>
<td>Prints the size of the specified log buffer and exits. </td>
</tr>
<tr>
<td><code>-n&nbsp;&lt;count&gt;</code></td>
<td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value is 4. Requires the <code>-r</code> option. </td>
</tr>
<tr>
<td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
<td>Rotates the log file every <code>&lt;kbytes&gt;</code> of output. The default value is 16. Requires the <code>-f</code> option. </td>
</tr>
<tr>
<td><code>-s</code></td>
<td>Sets the default filter spec to silent. </td>
</tr>
<tr>
<td><code>-v&nbsp;&lt;format&gt;</code></td>
<td>Sets the output format for log messages. The default is <code>brief</code> format. For a list of supported formats, see <a href="#outputformat">Controlling Log Output Format</a>.</td>
</tr>
</table>
<a name="stopping"></a>
<h2>Stopping the adb Server</h2>
<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p>
<p>To stop the adb server, use the <code>kill-server</code>. You can then restart the server by issuing any adb command. </p>
base/docs/html/guide/developing/tools/adt.html
+10
View File
@@ -0,0 +1,10 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=http://developer.android.com/sdk/eclipse-adt.html">
<title>Redirecting...</title>
</head>
<body>
<p>You should be redirected. Please <a
href="http://developer.android.com/sdk/eclipse-adt.html">click here</a>.</p>
</body>
</html>
base/docs/html/guide/developing/tools/aidl.jd
+305
View File
@@ -0,0 +1,305 @@
page.title=Designing a Remote Interface Using AIDL
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#implementing">Implementing IPC Using AIDL</a>
<ol>
<li><a href="#aidlsyntax">Create an .aidl File</a></li>
<li><a href="#implementtheinterface">Implementing the Interface</a></li>
<li><a href="#exposingtheinterface">Exposing Your Interface to Clients</a></li>
<li><a href="#parcelable">Pass by value Parameters using Parcelables</a></li>
</ol>
</li>
<li><a href="#calling">Calling an IPC Method</a></li>
</ol>
</div>
</div>
<p>Since each application runs in its own process, and you can write a service that
runs in a different process from your Application's UI, sometimes you need to pass objects
between processes. On the Android platform, one process can not normally access the memory
of another process. So to talk, they need to decompose their objects into primitives that
the operating system can understand, and "marshall" the object across that boundary for you.</p>
<p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it
for you.</p>
<p>AIDL (Android Interface Definition Language) is an <a
href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a>
language used to generate code that enables two processes on an Android-powered device
to talk using interprocess communication (IPC). If you have code
in one process (for example, in an Activity) that needs to call methods on an
object in another process (for example, a Service), you would use AIDL to
generate code to marshall the parameters.</p>
<p>The AIDL IPC mechanism
is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy
class to pass values between the client and the implementation. </p>
<h2 id="implementing">Implementing IPC Using AIDL</h2>
<p>Follow these steps to implement an IPC service using AIDL.</p>
<ol>
<li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This
file defines an interface (<em>YourInterface</em>.aidl) that defines the
methods and fields available to a client. </li>
<li><strong>Add the .aidl file to your makefile</strong> - (the ADT Plugin for Eclipse
manages this for you). Android includes the compiler, called
AIDL, in the <code>tools/</code> directory. </li>
<li><strong><a href="#implementtheinterface">Implement your interface methods</a></strong> -
The AIDL compiler creates an interface in the Java programming language from your AIDL interface.
This interface has an inner abstract class named Stub that inherits the
interface (and implements a few additional methods necessary for the IPC
call). You must create a class that extends <em>YourInterface</em>.Stub
and implements the methods you declared in your .aidl file. </li>
<li><strong><a href="#exposingtheinterface">Expose your interface to clients</a></strong> -
If you're writing a service, you should extend {@link
android.app.Service Service} and override {@link android.app.Service#onBind
Service.onBind(Intent)} to return an instance of your class that implements your
interface. </li>
</ol>
<h3 id="aidlsyntax">Create an .aidl File</h3>
<p>AIDL is a simple syntax that lets you declare an interface with one or more
methods, that can take parameters and return values. These parameters and return
values can be of any type, even other AIDL-generated interfaces. <em>However, it
is important to note</em> that you <em>must</em> import all non-built-in types,
<em>even if they are defined in the same package as your interface</em>.
Here are the data types that AIDL can support: </p>
<ul>
<li>Primitive Java programming language types (int, boolean, etc)
&mdash; No <code>import</code> statement is needed. </li>
<li>One of the following classes (no <code>import</code> statements needed):
<ul>
<li><strong>String</strong></li>
<li><strong>List</strong> - All elements in the List must be one of the types
in this list, including other AIDL-generated interfaces and
parcelables. List may optionally be used as a "generic" class (e.g.
List&lt;String&gt;).
The actual concrete class that the other side will receive
will always be an ArrayList, although the method will be generated
to use the List interface. </li>
<li><strong>Map</strong> - All elements in the Map must be of one of the
types in this list, including other AIDL-generated interfaces and
parcelables. Generic maps, (e.g. of the form Map&lt;String,Integer&gt;
are not supported.
The actual concrete class that the other side will receive
will always be a HashMap, although the method will be generated
to use the Map interface.</li>
<li><strong>CharSequence</strong> - This is useful for the CharSequence
types used by {@link android.widget.TextView TextView} and other
widget objects. </li>
</ul>
</li>
<li>Other AIDL-generated interfaces, which are always passed by reference.
An <code>import</code> statement is always needed for these.</li>
<li>Custom classes that implement the <a href="#parcelable">Parcelable
protocol</a> and are passed by value.
An <code>import</code> statement is always needed for these.</li>
</ul>
<p>Here is the basic AIDL syntax:</p>
<pre>// My AIDL file, named <em>SomeClass</em>.aidl
// Note that standard comment syntax is respected.
// Comments before the import or package statements are not bubbled up
// to the generated interface, but comments above interface/method/field
// declarations are added to the generated interface.
// Include your fully-qualified package statement.
package com.android.sample;
// See the list above for which classes need
// import statements (hint--most of them)
import com.android.sample.IAtmService;
// Declare the interface.
interface IBankAccountService {
// Methods can take 0 or more parameters, and
// return a value or void.
int getAccountBalance();
void setOwnerNames(in List&lt;String&gt; names);
// Methods can even take other AIDL-defined parameters.
BankAccount createAccount(in String name, int startingDeposit, in IAtmService atmService);
// All non-Java primitive parameters (e.g., int, bool, etc) require
// a directional tag indicating which way the data will go. Available
// values are in, out, inout. (Primitives are in by default, and cannot be otherwise).
// Limit the direction to what is truly needed, because marshalling parameters
// is expensive.
int getCustomerList(in String branch, out String[] customerList);
}</pre>
<h3 id="implementtheinterface">Implementing the Interface</h3>
<p>AIDL generates an interface file for you with the same name as your .aidl
file. If you are using the Eclipse plugin, AIDL will automatically be run as part of
the build process (you don't need to run AIDL first and then build your project).
If you are not using the plugin, you should run AIDL first. </p>
<p>The generated interface
includes an abstract inner class named Stub that declares all the methods
that you declared in your .aidl file. Stub also defines a few helper methods,
most notably asInterface(), which takes an IBinder (passed to a client's onServiceConnected()
implementation when applicationContext.bindService() succeeds), and returns an
instance of the interface used to call the IPC methods. See the section
<a href="#calling">Calling an IPC Method</a> for more details on how to make this cast.</p>
<p>To implement your interface, extend <em>YourInterface</em>.Stub,
and implement the methods. (You can create the .aidl file and implement the stub
methods without building between--the Android build process will process .aidl
files before .java files.) </p>
<p>Here is an example of implementing an interface called IRemoteService, which exposes
a single method, getPid(), using an anonymous instance:</p>
<pre>// No need to import IRemoteService if it's in the same project.
private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){
public int getPid(){
return Process.myPid();
}
}</pre>
<p>A few rules about implementing your interface: </p>
<ul>
<li>No exceptions that you throw will be sent back to the caller.</li>
<li>By default, IPC calls are synchronous. If you know that an IPC service takes more than
a few milliseconds to complete, you should not call it in the Activity/View thread,
because it might hang the application (Android might display an &quot;Application
is Not Responding&quot; dialog).
Try to call them in a separate thread. </li>
<li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li>
</ul>
<h3 id="exposingtheinterface">Exposing Your Interface to Clients</h3>
<p>Now that you've got your interface implementation, you need to expose it to clients.
This is known as &quot;publishing your service.&quot; To publish a service,
inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind
Service.onBind(Intent)} to return an instance of the class that implements your interface.
Here's a code snippet of a service that exposes the IRemoteService
interface to clients. </p>
<pre>public class RemoteService extends Service {
...
{@include development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java
exposing_a_service}
}</pre>
<h3 id="parcelable">Pass by value Parameters using Parcelables</h3>
<p>If you have a class that you would like to send from one process to another through
an AIDL interface, you can do that. You must ensure that the code for your class is available
to the other side of the IPC. Generally, that means that you're talking to a service that you
started.</p>
<p>There are five parts to making a class support the Parcelable protocol:</b>
<ol>
<li>Make your class implement the {@link android.os.Parcelable} interface.</li>
<li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the
current state of the object and writes it to a parcel.</li>
value in a parcel into your object.</li>
<li>Add a static field called <code>CREATOR</code> to your class which is an object implementing
the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li>
<li>Last but not least, create an aidl file
that declares your parcelable class (as shown below). If you are using a custom build process,
do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't
compiled.</li>
</ol>
<p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall
your objects.</p>
<p>Here is an example of how the {@link android.graphics.Rect} class implements the
Parcelable protocol.</p>
<pre class="prettyprint">
import android.os.Parcel;
import android.os.Parcelable;
public final class Rect implements Parcelable {
public int left;
public int top;
public int right;
public int bottom;
public static final Parcelable.Creator&lt;Rect&gt; CREATOR = new Parcelable.Creator&lt;Rect&gt;() {
public Rect createFromParcel(Parcel in) {
return new Rect(in);
}
public Rect[] newArray(int size) {
return new Rect[size];
}
};
public Rect() {
}
private Rect(Parcel in) {
readFromParcel(in);
}
public void writeToParcel(Parcel out) {
out.writeInt(left);
out.writeInt(top);
out.writeInt(right);
out.writeInt(bottom);
}
public void readFromParcel(Parcel in) {
left = in.readInt();
top = in.readInt();
right = in.readInt();
bottom = in.readInt();
}
}
</pre>
<p>Here is Rect.aidl for this example</p>
<pre class="prettyprint">
package android.graphics;
// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect;
</pre>
<p>The marshalling in the Rect class is pretty simple. Take a look at the other
methods on {@link android.os.Parcel} to see the other kinds of values you can write
to a Parcel.</p>
<p class="warning"><b>Warning:</b> Don't forget the security implications of receiving data from
other processes. In this case, the rect will read four numbers from the parcel,
but it is up to you to ensure that these are within the acceptable range of
values for whatever the caller is trying to do. See
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> for more
on how to keep your application secure from malware.</p>
<h2 id="calling">Calling an IPC Method</h2>
<p>Here are the steps a calling class should make to call your remote interface: </p>
<ol>
<li>Declare a variable of the interface type that your .aidl file defined. </li>
<li>Implement {@link android.content.ServiceConnection ServiceConnection}. </li>
<li>Call {@link android.content.Context#bindService(android.content.Intent,android.content.ServiceConnection,int)
Context.bindService()}, passing in your ServiceConnection implementation. </li>
<li>In your implementation of {@link android.content.ServiceConnection#onServiceConnected(android.content.ComponentName,android.os.IBinder)
ServiceConnection.onServiceConnected()}, you will receive an {@link android.os.IBinder
IBinder} instance (called <em>service</em>). Call <code><em>YourInterfaceName</em>.Stub.asInterface((IBinder)<em>service</em>)</code> to
cast the returned parameter to <em>YourInterface</em> type.</li>
<li>Call the methods that you defined on your interface. You should always trap
{@link android.os.DeadObjectException} exceptions, which are thrown when
the connection has broken; this will be the only exception thrown by remote
methods.</li>
<li>To disconnect, call {@link android.content.Context#unbindService(android.content.ServiceConnection)
Context.unbindService()} with the instance of your interface. </li>
</ol>
<p>A few comments on calling an IPC service:</p>
<ul>
<li>Objects are reference counted across processes. </li>
<li>You can send anonymous objects
as method arguments. </li>
</ul>
<p>Here is some sample code demonstrating calling an AIDL-created service, taken
from the Remote Service sample in the ApiDemos project.</p>
<p>{@sample development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java
calling_a_service}</p>
base/docs/html/guide/developing/tools/avd.jd
+447
View File
@@ -0,0 +1,447 @@
page.title=Android Virtual Devices
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>AVD quickview</h2>
<ul>
<li>You need to create an AVD to run any app in the Android emulator</li>
<li>Each AVD is a completely independent virtual device, with its own
hardware options, system image, and data storage.
<li>You create AVD configurations to model different device environments
in the Android emulator.</li>
<li>You can launch a graphical Android AVD Manager either through Eclipse or
through the <code>android</code> tool. The <code>android</code> tool also offers
a command-line interface for creating and managing AVDs.</li> </ul>
<h2>In this document</h2>
<ol>
<li><a href="#creating">Creating an AVD</a>
<ol>
<li><a href="#hardwareopts">Setting hardware emulation options</a></li>
<li><a href="#location">Default location of the AVD files</a></li>
</ol>
</li>
<li><a href="#managing">Managing AVDs</a>
<ol>
<li><a href="#moving">Moving an AVD</a></li>
<li><a href="#updating">Updating an AVD</a></li>
<li><a href="#deleting">Deleting an AVD</a></li>
</ol>
</li>
<li><a href="#options">Command-line options</a></li>
</ol>
<h2>See Also</h2>
<ol>
<li><a href="{@docRoot}guide/developing/tools/emulator.html">Android
Emulator</a></li>
</ol>
</div>
</div>
<p>Android Virtual Devices (AVDs) are configurations of emulator options that let
you better model an actual device.</p>
<p>Each AVD is made up of: </p>
<ul>
<li>A hardware profile.&nbsp;&nbsp;You can set options to define the hardware
features of the virtual device. For example, you can define whether the device
has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how
much memory it has, and so on. </li>
<li>A mapping to a system image.&nbsp;&nbsp;You can define what version of the
Android platform will run on the virtual device. You can choose a version of the
standard Android platform or the system image packaged with an SDK add-on.</li>
<li>Other options.&nbsp;&nbsp;You can specify the emulator skin you want to use
with the AVD, which lets you control the screen dimensions, appearance, and so
on. You can also specify the emulated SD card to use with the AVD.</li>
<li>A dedicated storage area on your development machine, in which is stored the
device's user data (installed applications, settings, and so on) and emulated SD
card.</li>
</ul>
<p>You can create as many AVDs as you need, based on the types of devices you
want to model and the Android platforms and external libraries you want to run
your application on. </p>
<p>In addition to the options in an AVD configuration, you can also
specify emulator command-line options at launch or by using the emulator
console to change behaviors or characteristics at run time. For a complete
reference of emulator options, please see the <a
href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a>
documentation. </p>
<p>The easiest way to create an AVD is to use the graphical AVD Manager, which
you can launch from Eclipse or from the command line using the
<code>android</code> tool. The <code>android</code> tool is provided in the
<code>tools/</code> directory of the Android SDK. When you run the
<code>android</code> tool without options, it launches the graphical AVD
Manager.</p>
<p>For more information about how to work with AVDs from inside your development
environment, see <a
href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with
ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in
Other IDEs</a>, as appropriate for your environment.</p>
<h2 id="creating">Creating an AVD</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<p>The Android SDK does not include any preconfigured AVDs, so
you need to create an AVD before you can run any application in the emulator
(even the Hello World application).</p>
</div>
</div>
<p>The easiest way to create an AVD is to use the graphical AVD Manager, but the
<code>android</code> tool also offers a <a href="#options">command line option</a>.</p>
<p>To create an AVD:</p>
<ol>
<li>In Eclipse, choose <strong>Window &gt; Android SDK and AVD Manager</strong>. </li>
<p>Alternatively, you can launch the graphical AVD Manager by running the
<code>android</code> tool with no options.</p>
<li>Select <strong>Virtual Devices</strong> in the left panel.</li>
<li>Click <strong>New</strong>. </li>
<p>The <strong>Create New AVD</strong> dialog appears.</p> <a
href="{@docRoot}images/developing/avd-dialog.png"><img
src="{@docRoot}images/developing/avd-dialog.png" alt="AVD
Dialog" /></a>
<li>Type the name of the AVD, such as "my_avd".</li>
<li>Choose a target. </li>
<p>The target is the system image that you want to run on the emulator,
from the set of platforms that are installed in your SDK environment. You can
choose a version of the standard Android platform or an SDK add-on. For more
information about how to add platforms to your SDK, see <a
href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. </p>
<li>Optionally specify any additional settings: </li>
<dl>
<dt><em>SD Card</em></dt> <dd>The path to the SD card image to use with this
AVD, or the size of a new SD card image to create for this AVD.</dd> </dl>
<dt><em>Skin</em></dt>
<dd>The skin to use for this AVD, identified by name or dimensions.</dd>
<dt><em>Hardware</em></dt>
<dd>The hardware emulation options for the device. For a list of the options, see
<a href="#hardwareopts">Setting hardware emulation options</a>.</dd>
</dl>
<li>Click <strong>Create AVD</strong>.</li>
</ol>
<h3 id="hardwareopts">Setting hardware emulation options</h3>
<p>When you create a new AVD that uses a standard Android system image ("Type:
platform"), the AVD Manager
lets you set hardware emulation
options for your virtual device.
The table below lists the options available and the
default values, as well as the names of properties that store the emulated
hardware options in the AVD's configuration file (the <code>config.ini</code> file in the
AVD's local directory). </p>
<table>
<tr>
<th>Characteristic</th>
<th>Description</th>
<th>Property</th>
</tr>
<tr>
<td>Device ram size</td>
<td>The amount of physical RAM on the device, in megabytes. Default value is "96".
<td>hw.ramSize</td>
</tr>
<tr>
<td>Touch-screen support</td>
<td>Whether there is a touch screen or not on the device. Default value is "yes".</td>
<td>hw.touchScreen
<tr>
<td>Trackball support </td>
<td>Whether there is a trackball on the device. Default value is "yes".</td>
<td>hw.trackBall</td>
</tr>
<tr>
<td>Keyboard support</td>
<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td>
<td>hw.keyboard</td>
</tr>
<tr>
<td>DPad support</td>
<td>Whether the device has DPad keys. Default value is "yes".</td>
<td>hw.dPad</td>
</tr>
<tr>
<td>GSM modem support</td>
<td>Whether there is a GSM modem in the device. Default value is "yes".</td>
<td>hw.gsmModem</td>
</tr>
<tr>
<td>Camera support</td>
<td>Whether the device has a camera. Default value is "no".</td>
<td>hw.camera</td>
</tr>
<tr>
<td>Maximum horizontal camera pixels</td>
<td>Default value is "640".</td>
<td>hw.camera.maxHorizontalPixels</td>
</tr>
<tr>
<td>Maximum vertical camera pixels</td>
<td>Default value is "480".</td>
<td>hw.camera.maxVerticalPixels</td>
</tr>
<tr>
<td>GPS support</td>
<td>Whether there is a GPS in the device. Default value is "yes".</td>
<td>hw.gps</td>
</tr>
<tr>
<td>Battery support</td>
<td>Whether the device can run on a battery. Default value is "yes".</td>
<td>hw.battery</td>
</tr>
<tr>
<td>Accelerometer</td>
<td>Whether there is an accelerometer in the device. Default value is "yes".</td>
<td>hw.accelerometer</td>
</tr>
<tr>
<td>Audio recording support</td>
<td>Whether the device can record audio. Default value is "yes".</td>
<td>hw.audioInput</td>
</tr>
<tr>
<td>Audio playback support</td>
<td>Whether the device can play audio. Default value is "yes".</td>
<td>hw.audioOutput</td>
</tr>
<tr>
<td>SD Card support</td>
<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td>
<td>hw.sdCard</td>
</tr>
<tr>
<td>Cache partition support</td>
<td>Whether we use a /cache partition on the device. Default value is "yes".</td>
<td>disk.cachePartition</td>
</tr>
<tr>
<td>Cache partition size</td>
<td>Default value is "66MB".</td>
<td>disk.cachePartition.size </td>
</tr>
<tr>
<td>Abstracted LCD density</td>
<td>Sets the generalized density characteristic used by the AVD's screen. Most
skins come with a value (which you can modify), but if a skin doesn't provide
its own value, the default is 160. </td>
<td>hw.lcd.density </td>
</tr>
<tr>
<td>Max VM application heap size</td>
<td>The maximum heap size a Dalvik application might allocate before being
killed by the system. Value is in megabytes. Most skins come with a value (which
you can modify), but if a skin doesn't provide its own value, the default is
16.</td>
<td>vm.heapSize</td>
</tr>
</table>
<h3 id="location">Default location of the AVD files</h3>
<p>When you create an AVD, the AVD Manager creates a dedicated directory for it
on your development computer. The directory contains the AVD configuration file,
the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system
image &mdash; instead, the AVD configuration file contains a mapping to the
system image, which it loads when the AVD is launched. </p>
<p>The AVD Manager also creates a <code>&lt;AVD name&gt;.ini</code> file for the
AVD at the root of the <code>.android/avd</code> directory on your computer. The file
specifies the location of the AVD directory and always remains at the root the
.android directory.</p>
<p>By default, the AVD Manager creates the AVD directory inside
<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and
Settings\&lt;user&gt;\.android\</code> on Windows XP, and
<code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista.
If you want to use a custom location for the AVD directory, you
can do so by using the <code>-p &lt;path&gt;</code> option when
you create the AVD (command line tool only): </p>
<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre>
<p>If the <code>.android</code> directory is hosted on a network drive, we recommend using
the <code>-p</code> option to place the AVD directory in another location.
The AVD's <code>.ini</code> file remains in the <code>.android</code> directory on the network
drive, regardless of the location of the AVD directory. </p>
<h2 id="managing">Managing AVDs</h2>
<p>The sections below provide more information about how to manage AVDs once you've created them. </p>
<h3 id="moving">Moving an AVD</h3>
<p>If you want to move or rename an AVD, you can do so using this command:</p>
<pre>android move avd -n &lt;name&gt; [-&lt;option&gt; &lt;value&gt;] ...</pre>
<p>The options for this command are listed in <a href="#options">Command-line
options for AVDs</a> at the bottom of this page. </p>
<h3 id="updating">Updating an AVD</h3>
<p>
If you rename or move the root directory of a platform (or add-on), an AVD configured to use that platform will no longer be able to load the system image properly. To fix the AVD, use the <strong>Repair...</strong> button in the AVD Manager. From the command line, you can also use the <code>android update avd</code> command to recompute the path to the system images.</p>
<h3 id="deleting">Deleting an AVD</h3>
<p>You can delete an AVD in the AVD Manager by selecting the
AVD and clicking <strong>Delete</strong>.</p>
<p>Alternatively, you can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p>
<pre>android delete avd -n &lt;name&gt; </pre>
<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the
specified name deletes the AVD's directory and files. </p>
<h2 id="options">Command-line options</h2>
<p>You can use the <code>android</code> tool to create and manage AVDs.</p>
<p>The command line for creating an AVD has the following syntax:</p>
<pre>
android create avd -n &lt;name&gt; -t &lt;targetID&gt; [-&lt;option&gt; &lt;value&gt;] ...
</pre>
<p>Here's an example that creates an AVD with the name "my_android2.2" and target ID "3":</p>
<pre>
android create avd -n my_android2.2 -t 3
</pre>
<p>The table below lists the command-line options you can use with the
<code>android</code> tool. </p>
<table>
<tr>
<th width="15%">Action</th>
<th width="20%">Option</th>
<th width="30%">Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>list&nbsp;avds</code></td>
<td>&nbsp;</td>
<td>List all known AVDs, with name, path, target, and skin. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="6"><code>create&nbsp;avd</code></td>
<td><code>-n &lt;name&gt; or <br></code></td>
<td>The name for the AVD.</td>
<td>Required</td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target ID of the system image to use with the new AVD.</td>
<td>Required. To obtain a list of available targets, use <code>android list
targets</code>.</td>
</tr>
<tr>
<td><code>-c &lt;path&gt;</code> or <br>
<code>-c &lt;size&gt;[K|M]</code></td>
<td>The path to the SD card image to use with this AVD or the size of a new SD
card image to create for this AVD.</td>
<td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td>
</tr>
<tr>
<td><code>-f</code></td>
<td>Force creation of the AVD</td>
<td>By default, if the name of the AVD being created matches that of an
existing AVD, the <code>android</code> tool will not create the new AVD or overwrite
the existing AVD. If you specify the <code>-f</code> option, however, the
<code>android</code> tool will automatically overwrite any existing AVD that has the
same name as the new AVD. The files and data of the existing AVD are
deleted. </td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Path to the location at which to create the directory for this AVD's
files.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-s &lt;name&gt;</code> or <br>
<code>-s &lt;width&gt;-&lt;height&gt;</code> </td>
<td>The skin to use for this AVD, identified by name or dimensions.</td>
<td>The <code>android</code> tool scans for a matching skin by name or dimension in the
<code>skins/</code> directory of the target referenced in the <code>-t
&lt;targetID&gt;</code> argument. Example: <code>-s HVGA-L</code></td>
</tr>
<tr>
<td><code>delete&nbsp;avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>Delete the specified AVD.</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="3"><code>move&nbsp;avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the AVD to move.</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>The path to the new location for the AVD.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-r &lt;new-name&gt;</code></td>
<td>Rename the AVD.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>update&nbsp;avds</code></td>
<td>&nbsp;</td>
<td>Recompute the paths to all system images.</td>
<td>&nbsp;</td>
</tr>
</table>
base/docs/html/guide/developing/tools/bmgr.jd
+191
View File
@@ -0,0 +1,191 @@
page.title=bmgr
@jd:body
<!-- quickview box content here -->
<div id="qv-wrapper">
<div id="qv">
<h2>bmgr quickview</h2>
<p><code>bmgr</code> lets you control the backup/restore system on an Android device.
<h2>In this document</h2>
<ol>
<li><a href="#backup">Forcing a Backup Operation</a></li>
<li><a href="#restore">Forcing a Restore Operation</a></li>
<li><a href="#other">Other Commands</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>
</ol>
</div>
</div>
<!-- normal page content here -->
<p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager
on Android devices supporting API Level 8 or greater. It provides commands to induce backup
and restore operations so that you don't need to repeatedly wipe data or take similar
intrusive steps in order to test your application's backup agent. These commands are
accessed via the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> shell.
<p>For information about adding support for backup in your application, read <a
href="{@docRoot}guide/topics/data/backup.html">Data Backup</a>, which includes a guide to testing
your application using {@code bmgr}.</p>
<h2 id="backup">Forcing a Backup Operation</h2>
<p>Normally, your application must notify the Backup Manager when its data has changed, via {@link
android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} implementation at some time in the future. However, instead of calling {@link
android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
line by running the <code>bmgr backup</code> command:
<pre class="no-pretty-print">adb shell bmgr backup <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application you wish to
schedule for
backup. When you execute this backup command, your application's backup agent will be invoked to
perform a backup operation at some time in the future (via your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method), though there is no guarantee when it will occur. However, you can force all
pending backup operations to run immediately by using the <code>bmgr run</code> command:
<pre class="no-pretty-print">adb shell bmgr run</pre>
<p>This causes a backup pass to execute immediately, invoking the backup agents of all applications
that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
last backup operation, plus any applications which had been manually scheduled for
backup via <code>bmgr backup</code>.
<h2 id="restore">Forcing a Restore Operation</h2>
<p>Unlike backup operations, which are batched together and run on an occasional basis, restore
operations execute immediately. The Backup Manager currently provides two kinds of restore
operations. The first kind restores an entire device with the data that has been backed up. This
is typically performed only when a device is first provisioned (to replicate settings and other
saved state from the user's previous device) and is an operation that only the system can
perform. The second kind of restore operation restores
a single application to its "active" data set; that is, the application will abandon its current
data and revert to the last-known-good data that is held in the current backup image. You can
invoke this second restore operation with the {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The
Backup Manager will then invoke your backup agent's {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} implementation.
<p>While testing your application, you can immediately invoke the restore operation (bypassing the
{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
for your application by using the <code>bmgr restore</code> command:
<pre class="no-pretty-print">adb shell bmgr restore <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal Java-style package name of the application
participating in the backup/restore mechanism, which you would like to restore. The Backup
Manager will immediately instantiate the application's backup agent and invoke it for restore. This
will happen even if your application is not currently running.
<h2 id="other">Other Commands</h2>
<h3>Wiping data</h3>
<p>The data for a single application can be erased from the active data set on demand. This is
very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
or saved state information. You can wipe an application's data with the <code>bmgr wipe</code>
command:
<pre class="no-pretty-print">adb shell bmgr wipe <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application whose data
you wish to
erase. The next backup operation that the application's agent processes will look as
though the application had never backed anything up before.
<h3>Enabling and disabling backup</h3>
<p>You can see whether the Backup Manager is operational at all with the <code>bmgr
enabled</code> command:
<pre class="no-pretty-print">adb shell bmgr enabled</pre>
<p>This might be useful if your application's backup agent is never being invoked for backup, to
verify whether the operating system thinks it should be performing such operations at all.</p>
<p>You can also directly disable or enable the Backup Manager with this command:
<pre class="no-pretty-print">adb shell bmgr enable <em>&lt;boolean&gt;</em></pre>
<p><code><em>&lt;boolean&gt;</em></code> is either <code>true</code> or <code>false</code>.
This is equivalent to disabling or enabling backup in the device's main Settings UI.</p>
<p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport
will explicitly wipe
the entire active data set from its backend storage. This is so that when a user says
they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further
data will be saved from the device, and no restore operations will be possible, unless the Backup
Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command).
<!-- The following is not useful to applications, but may be some useful information some day...
<h2 id="transports">Applying a Backup Transport</h2>
<p>A "backup transport" is the code module responsible for moving backup and restore data
to and from some storage location. A device can have multipe transports installed, though only
one is active at any given time. Transports are identified by name. You can see what
transports are available on your device or emulator by running the
<code>bmgr list transports</code> command:
<pre class="no-pretty-print">adb shell bmgr list transports</pre>
<p>The output of this command is a list of the transports available on the device. The currently
active transport is flagged with a <code>*</code> character. Transport names may look like
component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>),
but they need not be, and the strings are never used as direct class references. The use of
a component-like naming scheme is simply for purposes of preventing name collisions.
<p>You can change which transport is currently active from the command line as well:
<pre class="no-pretty-print">adb shell bmgr transport <em>&lt;name&gt;</em></pre>
<p><code><em>&lt;name&gt;</em></code> is one of the names as printed by the <code>bmgr list
transports</code>
command. From this point forward, backup and restore operations will be directed through the
newly-selected transport. Backup state tracking is managed separately for each transport, so
switching back and forth between them will not corrupt the saved state.
<h2 id="restoresets">Viewing Restore Sets</h2>
<p>All of the application data that a device has written to its backup transport is tracked
as a group that is collectively called a "restore set," because each data set is
most often manipulated during a restore operation. When a device is provisioned for the first
time, a new restore set is established. You can get a listing of all the restore sets available to
the current transport by running the <code>bmgr list sets</code> command:
<pre class="no-pretty-print">adb shell bmgr list sets</pre>
<p>The output is a listing of available restore sets, one per line. The first item on each line is
a token (a hexadecimal value that identifies the restore set to the transport). Following
the token is a string that briefly identifies the restore set.
Only the token is used within the backup and restore mechanism.
-->
base/docs/html/guide/developing/tools/ddms.jd
+251
View File
@@ -0,0 +1,251 @@
page.title=Using the Dalvik Debug Monitor
@jd:body
<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS),
which provides port-forwarding services, screen capture on the device, thread
and heap information on the device, logcat, process, and radio state information,
incoming call and SMS spoofing, location data spoofing, and more. This page
provides a modest discussion of DDMS features; it is not an exhaustive exploration of
all the features and capabilities.</p>
<p>DDMS ships in the <code>tools/</code> directory of the SDK.
Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code>
on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are
connected and running simultaneously, DDMS defaults to the emulator.</p>
<h2 id="how-ddms-works">How DDMS works</h2>
<p>DDMS acts as a middleman to connect the IDE to the applications running on
the device. On Android, every application runs in its own process,
each of which hosts its own virtual machine (VM). And each process
listens for a debugger on a different port.</p>
<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and
starts a device monitoring service between the two, which will notify DDMS when a device is
connected or disconnected. When a device is connected, a VM monitoring service is created
between adb and DDMS, which will notify DDMS when a VM on the device is started
or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb,
and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device.
DDMS can now talk to the VM using a custom wire protocol.</p>
<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p>
<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p>
<p>For more information on port-forwarding with DDMS,
read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach
to port 8700 for debugging</a>.</p>
<p class="note"><strong>Tip:</strong>
You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>.
Preferences are saved to &quot;$HOME/.ddmsrc&quot;. </p>
<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/>
Debugging an application in the Dalvik VM should work the same as it does
in other VMs. However, when single-stepping out of synchronized code, the "current line"
cursor may jump to the last line in the method for one step.</p>
<h2 id="left-pane">Left Pane</h2>
<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of
all the VMs currently running within each.
VMs are identified by the package name of the application it hosts.</p>
<p>Use this list to find and attach to the VM
running the activity(ies) that you want to debug. Next to each VM in the
list is a &quot;debugger pass-through&quot; port (in the right-most column).
If you connect your debugger to one of the the ports listed, you
will be connected to the corresponding VM on the device. However, when using
DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the
currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.)
This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p>
<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()}
(or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer
options</a>), a red icon will be shown next to the client name, while it waits for the
debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p>
<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a
connection between the debugger and the VM because it was unable to open the VM's local port.
If you see this for all VMs on the device, it is likely because you have another instance of
DDMS running (this includes the Eclipse plugin).</p>
<p>If you see a question mark in place of an application package, this means that,
once DDMS received the application pid from adb, it
somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p>
<h2 id="right-pane">Right pane</h2>
<p>On the right side, the Debug Monitor provides tabs that display useful information
and some pretty cool tools.</p>
<h3 id="info">Info</h3>
<p>This view shows some general information about the selected VM, including the process
ID, package name, and VM version.</p>
<h3 id="threads">Threads</h3>
<p> The threads view has a list of threads running in the process of the target VM.
To reduce the amount
of data sent over the wire, the thread updates are only sent when explicitly
enabled by toggling the &quot;threads&quot; button
in the toolbar. This toggle is maintained per VM. This tab includes the following
information: </p>
<ul>
<li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are
odd numbers starting from 3. </li>
<li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process,
this will match the process ID. </li>
<li> <strong>Status</strong> - the VM thread status. Daemon threads are
shown with an asterisk (*). This will be one of the following:
<ul>
<li> <em>running</em> - executing application code </li>
<li> <em>sleeping</em> - called Thread.sleep() </li>
<li> <em>monitor</em> - waiting to acquire a monitor lock </li>
<li> <em>wait</em> - in Object.wait() </li>
<li> <em>native</em> - executing native code </li>
<li> <em>vmwait</em> - waiting on a VM resource </li>
<li> <em>zombie</em> - thread is in the process of dying </li>
<li> <em>init</em> - thread is initializing (you shouldn't see this) </li>
<li> <em>starting</em> - thread is about to start (you shouldn't see
this either) </li>
</ul>
</li>
<li> <strong>utime</strong> - cumulative time spent executing user code, in &quot;jiffies&quot; (usually
10ms). </li>
<li> <strong>stime</strong> - cumulative time spent executing system code, in &quot;jiffies&quot; (usually
10ms). </li>
<li> <strong>Name</strong> - the name of the thread</li>
</ul>
<p> &quot;ID&quot; and &quot;Name&quot; are set when the thread is started. The remaining
fields are updated periodically (default is every 4 seconds). </p>
<h3 id="vm-heap">VM Heap</h3>
<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected,
the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button,
located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong>
to perform garbage collection and update the heap stats.</p>
<h3 id="allocation-tracker">Allocation Tracker</h3>
<p>In this view, you can track the memory allocation of each virtual machine.
With a VM selected in the left pane, click <strong>Start Tracking</strong>, then
<strong>Get Allocations</strong> to view all allocations since tracking started.
The table below will be filled with all the relevant
data. Click it again to refresh the list.</p>
<h3 id="emulator-control">Emulator Control</h3>
<p>With these controls, you can simulate special device states and activities.
Features include:</p>
<ul>
<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans
(home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency
(GPRS, EDGE, UTMS, etc.).</li>
<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li>
<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform
location-aware operations like GPS mapping.
<p>To use the Location Controls, launch your application in the Android emulator and open DDMS.
Click the Emulator Controls tab and scroll down to Location Controls.
From here, you can:</p>
<ul class="listhead">
<li>Manually send individual longitude/latitude coordinates to the device.
<p>Click <strong>Manual</strong>,
select the coordinate format, fill in the fields and click <strong>Send</strong>.
</p>
</li>
<li>Use a GPX file describing a route for playback to the device.
<p>Click <strong>GPX</strong> and load the file. Once loaded,
click the play button to playback the route for your location-aware application.</p>
<p>When performing playback from GPX, you can adjust the speed of
playback from the DDMS panel and control playback with the pause and skip buttons.
DDMS will parse both the waypoints (<code>&lt;wpt></code>, in the first table),
and the tracks (<code>&lt;trk></code>,
in the second table, with support for multiple segments, <code>&lt;trkseg></code>,
although they are simply
concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply
sends its coordinate to the device, while selecting a track lets you play it.</p>
</li>
<li>Use a KML file describing individual placemarks for sequenced playback to the device.
<p>Click <strong>KML</strong> and load the file. Once loaded,
click the play button to send the coordinates to your location-aware application.</p>
<p>When using a KML file, it is parsed for a <code>&lt;coordinates&gt;</code>
element. The value of which should be a single
set of longitude, latitude and altitude figures. For example:</p>
<pre>&lt;coordinates>-122.084143,37.421972,4&lt;/coordinates></pre>
<p>In your file, you may include multiple <code>&lt;Placemark></code> elements, each containing
a <code>&lt;coordinates></code> element. When you do so, the collection of placemarks will
be added as tracks. DDMS will send one placemark per second to the device.</p>
<p>One way to generate a suitable KML file is to find a location in Google Earth.
Right-click the location entry that appears on the left and select "Save place as..."
with the save format set to Kml.</p>
<p class="note"><strong>Note:</strong> DDMS does not support routes created with the
<code>&lt;MultiGeometry>&lt;LineString>lat1, long1, lat2, long2, ....&lt;/LineString>&lt;/MultiGeometry></code> methods.
There is also currently no support for the <code>&lt;TimeStamp></code> node inside
the <code>&lt;Placemark></code>.
Future releases may support timed placement and routes within a single coordinate element.</p>
</li>
</ul>
<p>For <em>additional</em> methods of setting up mocks of location-based data, see the
<a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p>
</li>
</ul>
<!-- <h4>Event Log</h4> -->
<h2 id="file-explorer">File Explorer</h2>
<p>With the File Explorer, you can view the device file system and perform basic management,
like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>
<code>push</code> and <code>pull</code> commands, with a GUI experience.</p>
<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the
File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them.
To copy files from the device, select the file and click the <strong>Pull File from Device</strong>
button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p>
<p>If you're interested in using an SD card image on the emulator, you're still required to use
the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup.
For example, from the <code>/tools</code> directory, execute:</p>
<pre>
<b>$</b> mksdcard 1024M ./img
<b>$</b> emulator -sdcard ./img
</pre>
<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the
sdcard directory. However, your files may not appear automatically. For example, if you add an
MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting
the emulator from command line, be sure to mount the sdcard again.)</p>
<p>For more information on creating an SD card image, see the
<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p>
<h2 id="screen-capture">Screen Capture</h2>
<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong>
&gt; <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.
Be sure to select a device first.</p>
<h2 id="exploring-processes">Exploring Processes</h2>
<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong>
&gt; <strong>Show process status</strong>... in the menu bar.</p>
<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2>
<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p>
<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2>
<ul>
<li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> &gt;
<strong>Run logcat...</strong> in the menu bar.</li>
<li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> &gt; <strong>Dump device
state...</strong> in the menu bar. </li>
</ul>
<h2 id="examine-radio-state">Examine Radio State</h2>
<p>By default, radio state is not output during a standard logcat (it is a lot of
information). To see radio information, either click <strong>Device</strong> &gt; <strong>Dump radio
state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging
Radio Information</a>. </p>
<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2>
<p>You can stop a virtual machine by selecting <strong>Actions</strong> &gt; <strong>Halt
VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p>
<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2>
<p>DDMS has the following known limitations:</p>
<ul>
<li>If you connect and disconnect a debugger, ddms drops and reconnects the
client so the VM realizes that the debugger has gone away. This will be fixed
eventually. </li>
</ul>
base/docs/html/guide/developing/tools/draw9patch.jd
+57
View File
@@ -0,0 +1,57 @@
page.title=Draw 9-patch
@jd:body
<p>The Draw 9-patch tool allows you to easily create a
{@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p>
<p>For an introduction to Nine-patch graphics and how they work, please read
the section about Nine-patch in the
<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a>
document.</p>
<img src="{@docRoot}images/draw9patch-norm.png" style="float:right" alt="" height="300" width="341"
/>
<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool.
You'll need the PNG image with which you'd like to create a NinePatch.</p>
<ol>
<li>From a terminal, launch the <code>draw9patch</code> application from your SDK
<code>/tools</code> directory.
</li>
<li>Drag your PNG image into the Draw 9-patch window
(or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file).
Your workspace will now open.
<p>The left pane is your drawing area, in which you can edit the lines for the
stretchable patches and content area. The right
pane is the preview area, where you can preview your graphic when stretched.</p>
</li>
<li>Click within the 1-pixel perimeter to draw the lines that define the stretchable
patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase
previously drawn lines.
</li>
<li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong>
<p>Your image will be saved with the <code>.9.png</code> file name.</p>
</li>
</ol>
<p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be
loaded with an empty one-pixel border added around the image, in which you can draw
the stretchable patches and content area.
A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is,
with no drawing area added, because it already exists.</p>
<img src="{@docRoot}images/draw9patch-bad.png" style="float:right" alt="" height="300" width="341"
/>
<p>Optional controls include:</p>
<ul>
<li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li>
<li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li>
<li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li>
<li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a
stretchable patch).</li>
<li><strong>Show content</strong>: Highlight the content area in the preview images
(purple is the area in which content is allowed).</li>
<li><strong>Show bad patches</strong>: Adds a red border around patch areas that may
produce artifacts in the graphic when stretched. Visual coherence of your stretched
image will be maintained if you eliminate all bad patches.</li>
<ul>
base/docs/html/guide/developing/tools/emulator.jd
+1771
View File
File diff suppressed because it is too large Load Diff
base/docs/html/guide/developing/tools/hierarchy-viewer.jd
+98
View File
@@ -0,0 +1,98 @@
page.title=Hierarchy Viewer
@jd:body
<p>The Hierarchy Viewer application allows you to debug and optimize your user
interface. It provides a visual representation of the layout's View hierarchy
(the Layout View) and a magnified inspector of the display (the Pixel Perfect View).
</p>
<p>To get the Hierarchy Viewer started:</p>
<ol>
<li>Connect your device or launch an emulator.</li>
<li>From a terminal, launch <code>hierarchyviewer</code> from your SDK
<code>/tools</code> directory.
</li>
<li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is
selected, a list of currently active <strong>Windows</strong> is displayed
on the right. The <em>&lt;Focused Window></em> is the window currently in
the foreground, and also the default window loaded if you do not select another.
</li>
<li>Select the window that you'd like to inspect and click
<strong>Load View Hierarchy</strong>. The Layout View will be loaded.
You can then load the Pixel Perfect View by clicking the second
icon at the bottom-left of the window.
</li>
</ol>
<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong>
to refresh the list of available windows on the right.</p>
<h2>Layout View</h2>
<p>The Layout View offers a look at the View layout and properties. It has three views:</p>
<ul>
<li>Tree View: a hierarchy diagram of the Views, on the left.</li>
<li>Properties View: a list of the selected View's properties, on the top-right.</li>
<li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li>
</ul>
<br/>
<img src="{@docRoot}images/hierarchyviewer-layout.png" alt="" height="509" width="700" />
<p>Select a node in the Tree View to display the properties of that element in
the Properties View. When a node is selected, the Wire-frame View
also indicates the bounds of the element with a red rectangle.
Double click a node in the tree (or select it, and click <strong>Display
View</strong>) to open a new window with a rendering of that element.</p>
<p>The Layout View includes a couple other helpful features for debugging your layout:
<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the
respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()},
on the View element currently selected in the tree. Calling these methods on any View can
be very useful when simultaneously running a debugger on your application.</p>
<p>The Tree View can be resized by adjusting the zoom slider, below
the diagram. The number of View elements in the window is also given here. You
should look for ways to minimize the number of Views. The fewer View elements there
are in a window, the faster it will perform.</p>
<p>If you interact with the device and change the focused View, the diagram will not automatically refresh.
You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>.
<h2>Pixel Perfect View</h2>
<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p>
<ul>
<li>Explorer View: shows the View hierarchy as a list, on the left.</li>
<li>Normal View: a normal view of the device window, in the middle.</li>
<li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li>
</ul>
<br/>
<img src="{@docRoot}images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" />
<p>Click on an element in the Explorer View and a "layout box" will be drawn in the
Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates
the normal bounds of the element (the height and width). The inner white or black rectangle indicates
the content bounds, when padding is present. A black or white rectangle outside the normal purple/green
rectangle indicates any present margins.
(There are two colors for each rectangle, in order to provide the best contrast
based on the colors currently in the background.)</p>
<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe
Views. For example, you might have a mock-up image of how you'd like to layout your interface.
By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the
image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p>
<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the
Explorer View does not. If you navigate away and focus on a different View, then you should refresh the
Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true
when you're working in a window that holds multiple Views that are not always visible. If you do not,
although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box
in the Normal View, because the hierarchy believes you are still focused on the prior View.</p>
<p>Optional controls include:</p>
<ul>
<li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li>
<li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li>
<li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li>
</ul>
base/docs/html/guide/developing/tools/index.jd
+109
View File
@@ -0,0 +1,109 @@
page.title=Tools Overview
@jd:body
<img src="{@docRoot}assets/images/android_wrench.png" alt="" align="right">
<p>The Android SDK includes a variety of custom tools that help you develop mobile
applications on the Android platform. The most important of these are the Android
Emulator and the Android Development Tools plugin for Eclipse, but the SDK also
includes a variety of other tools for debugging, packaging, and installing your
applications on the emulator. </p>
<dl>
<dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt>
<dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment,
making creating and debugging your Android applications easier and faster. If you
use Eclipse, the ADT plugin gives you an incredible boost in developing Android
applications.</dd>
<dt><a href="emulator.html">Android Emulator</a></dt>
<dd>A QEMU-based device-emulation tool that you can use to design,
debug, and test your applications in an actual Android run-time environment. </dd>
<dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt>
<dd>Virtual device configurations that you create, to model device
characteristics in the Android Emulator. In each configuration, you can
specify the Android platform to run, the hardware options, and the
emulator skin to use. Each AVD functions as an independent device with
it's own storage for user data, SD card, and so on. </dd>
<dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt>
<dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface.
It provides a visual representation of your layout's hierarchy of Views and a magnified inspector
of the current display with a pixel grid, so you can get your layout just right.
</dd>
<dt><a href="layoutopt.html">layoutopt</a></dt>
<dd>This tool lets you quickly analyze your application's layouts for
efficiency.
</dd>
<dt><a href="draw9patch.html">Draw 9-patch</a></dt>
<dd>The Draw 9-patch tool allows you to easily create a
{@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched
versions of the image, and highlights the area in which content is allowed.
</dd>
<dt><a href="ddms.html" >Dalvik Debug Monitor
Service</a> (ddms)</dt>
<dd>Integrated with Dalvik, the Android platform's custom VM, this tool
lets you manage processes on an emulator or device and assists in debugging.
You can use it to kill processes, select a specific process to debug,
generate trace data, view heap and thread information, take screenshots
of the emulator or device, and more. </dd>
<dt><a href="adb.html" >Android Debug Bridge</a> (adb)</dt>
<dd>The adb tool lets you install your application's .apk files on an
emulator or device and access the emulator or device from a command line.
You can also use it to link a standard debugger to application code running
on an Android emulator or device.
<p>This is located in {@code &lt;sdk&gt;/platform-tools/}.</p></dd>
<dt><a href="aapt.html">Android Asset
Packaging Tool</a> (aapt)</dt>
<dd>The aapt tool lets you create .apk files containing the binaries and
resources of Android applications.</dd>
<dt><a href="aidl.html" >Android Interface
Description Language</a> (aidl)</dt>
<dd>Lets you generate code for an interprocess interface, such as what
a service might use.</dd>
<dt><a href="adb.html#sqlite">sqlite3</a></dt>
<dd>Included as a convenience, this tool lets you access the SQLite data
files created and used by Android applications.</dd>
<dt><a href="traceview.html" >Traceview</a></dt>
<dd> This tool produces graphical analysis views of trace log data that you
can generate from your Android application. </dd>
<dt><a href="othertools.html#mksdcard">mksdcard</a></dt>
<dd>Helps you create a disk image that you can use with the emulator,
to simulate the presence of an external storage card (such as an SD card).</dd>
<dt><a href="othertools.html#dx">dx</a></dt>
<dd>The dx tool rewrites .class bytecode into Android bytecode
(stored in .dex files.)</dd>
<dt><a href="monkey.html">UI/Application
Exerciser Monkey</a></dt>
<dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-
level events. You can use the Monkey to stress-test applications that you are developing,
in a random yet repeatable manner.</dd>
<dt><a href="monkeyrunner_concepts.html">monkeyrunner</a></dt>
<dd>
The monkeyrunner tool provides an API for writing Python programs that control an Android device
or emulator from outside of Android code.
</dd>
<dt><a href="othertools.html#android">android</a></dt>
<dd>A script that lets you manage AVDs and generate <a
href="http://ant.apache.org/" title="Ant">Ant</a> build files that
you can use to compile your Android applications. </dd>
<dt><a href="zipalign.html">zipalign</a></dt>
<dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts
with a particular alignment relative to the start of the file. This should always be used
to align .apk files after they have been signed.</dd>
</dl>
base/docs/html/guide/developing/tools/layoutopt.jd
+62
View File
@@ -0,0 +1,62 @@
page.title=layoutopt
@jd:body
<p><code>layoutopt</code> is a command-line tool that helps you optimize the
layouts and layout hierarchies of your applications. You can run it against your
layout files or resource directories to quickly check for inefficiencies or
other types of problems that could be affecting the performance of your
application. </p>
<p>To run the tool, open a terminal and launch <code>layoutopt
&lt;resources&gt;</code> from your SDK <code>tools/</code> directory. In the
command, supply a list of uncompiled resource xml files or directories that you
want to analyze. </p>
<p>When run, the tool loads the specified XML files and analyzes their layout
structures and hierarchies according to a set of predefined rules. If it detects
issues, it outputs information about the issues, giving filename, line numbers,
description of issue, and for some types of issues a suggested resolution. </p>
<p>Here's an example of the output:</p>
<pre>$ layoutopt samples/
samples/compound.xml
7:23 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
11:21 This LinearLayout layout or its FrameLayout parent is useless
samples/simple.xml
7:7 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
samples/too_deep.xml
-1:-1 This layout has too many nested layouts: 13 levels, it should have &lt= 10!
20:81 This LinearLayout layout or its LinearLayout parent is useless
24:79 This LinearLayout layout or its LinearLayout parent is useless
28:77 This LinearLayout layout or its LinearLayout parent is useless
32:75 This LinearLayout layout or its LinearLayout parent is useless
36:73 This LinearLayout layout or its LinearLayout parent is useless
40:71 This LinearLayout layout or its LinearLayout parent is useless
44:69 This LinearLayout layout or its LinearLayout parent is useless
48:67 This LinearLayout layout or its LinearLayout parent is useless
52:65 This LinearLayout layout or its LinearLayout parent is useless
56:63 This LinearLayout layout or its LinearLayout parent is useless
samples/too_many.xml
7:413 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
-1:-1 This layout has too many views: 81 views, it should have &lt= 80!
samples/useless.xml
7:19 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
11:17 This LinearLayout layout or its FrameLayout parent is useless</pre>
<p>The <code>layoutopt</code> tool is available in SDK Tools, Revision 3 or
later. If you do not have SDK Tools r3 or later installed in your SDK, you can
download it from the Android SDK repository site using the Android SDK and AVD
Manager. For information, see <a
href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p>
<h3>Usage</h3>
<p>To run <code>layoutopt</code> against a given list of layout resources:</p>
<pre>layoutopt &lt;list of xml files or directories></pre>
<p>For example:</p>
<pre>$ layoutopt res/layout-land</pre>
<pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre>
base/docs/html/guide/developing/tools/monkey.jd
+240
View File
@@ -0,0 +1,240 @@
page.title=UI/Application Exerciser Monkey
@jd:body
<p>The Monkey is a program that runs on your
<a href="{@docRoot}guide/developing/tools/emulator.html">emulator</a> or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-level
events. You can use the Monkey to stress-test applications that you are developing, in a random
yet repeatable manner.</p>
<a name="overview"></a>
<h2>Overview</h2>
<p>The Monkey is a command-line tool that that you can run on any emulator
instance or on a device. It sends a pseudo-random stream of
user events into the system, which acts as a stress test on the application software you are
developing.</p>
<p>The Monkey includes a number of options, but they break down into four primary
categories:</p>
<ul>
<li>Basic configuration options, such as setting the number of events to attempt.</li>
<li>Operational constraints, such as restricting the test to a single package.</li>
<li>Event types and frequencies.</li>
<li>Debugging options.</li>
</ul>
<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i>
the system under test and looks for three conditions, which it treats specially:</p>
<ul>
<li>If you have constrained the Monkey to run in one or more specific packages, it
watches for attempts to navigate to any other packages, and blocks them.</li>
<li>If your application crashes or receives any sort of unhandled exception, the Monkey
will stop and report the error.</li>
<li>If your application generates an <i>application not responding</i> error, the Monkey
will stop and report the error.</li>
</ul>
<p>Depending on the verbosity level you have selected, you will also see reports on the progress
of the Monkey and the events being generated.</p>
<a name="basics"></a>
<h2>Basic Use of the Monkey</h2>
<p>You can launch the Monkey using a command line on your development machine or from a script.
Because the Monkey runs in the emulator/device environment, you must launch it from a shell in
that environment. You can do this by prefacing <code>adb shell</code> to each command,
or by entering the shell and entering Monkey commands directly.</p>
<p>The basic syntax is: </p>
<pre>$ adb shell monkey [options] &lt;event-count&gt;</pre>
<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send
events to any (and all) packages installed on your target. Here is a more typical command line,
which will launch your application and send 500 pseudo-random events to it:</p>
<pre>$ adb shell monkey -p your.package.name -v 500</pre>
<a name="reference"></a>
<h2>Command Options Reference</h2>
<p>The table below lists all options you can include on the Monkey command line.</p>
<table>
<tr>
<th>Category</th>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="2">General</td>
<td><code>--help</code></td>
<td>Prints a simple usage guide.</td>
</tr>
<tr>
<td><code>-v</code></td>
<td>Each -v on the command line will increment the verbosity level.
Level 0 (the default) provides little information beyond startup notification, test completion, and
final results.
Level 1 provides more details about the test as it runs, such as individual events being sent to
your activities.
Level 2 provides more detailed setup information such as activities selected or not selected for
testing.</td>
</tr>
<tr>
<td rowspan="10">Events</td>
<td><code>-s &lt;seed&gt;</code></td>
<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed
value, it will generate the same sequence of events.</td>
</tr>
<tr>
<td><code>--throttle &lt;milliseconds&gt;</code></td>
<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey.
If not specified, there is no delay and the events are generated as rapidly as possible.</td>
</tr>
<tr>
<td><code>--pct-touch &lt;percent&gt;</code></td>
<td>Adjust percentage of touch events.
(Touch events are a down-up event in a single place on the screen.)</td>
</tr>
<tr>
<td><code>--pct-motion &lt;percent&gt;</code></td>
<td>Adjust percentage of motion events.
(Motion events consist of a down event somewhere on the screen, a series of pseudo-random
movements, and an up event.)</td>
</tr>
<tr>
<td><code>--pct-trackball &lt;percent&gt;</code></td>
<td>Adjust percentage of trackball events.
(Trackball events consist of one or more random movements, sometimes followed by a click.)</td>
</tr>
<tr>
<td><code>--pct-nav &lt;percent&gt;</code></td>
<td>Adjust percentage of "basic" navigation events.
(Navigation events consist of up/down/left/right, as input from a directional input device.)</td>
</tr>
<tr>
<td><code>--pct-majornav &lt;percent&gt;</code></td>
<td>Adjust percentage of "major" navigation events.
(These are navigation events that will typically cause actions within your UI, such as
the center button in a 5-way pad, the back key, or the menu key.)</td>
</tr>
<tr>
<td><code>--pct-syskeys &lt;percent&gt;</code></td>
<td>Adjust percentage of "system" key events.
(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call,
End Call, or Volume controls.)</td>
</tr>
<tr>
<td><code>--pct-appswitch &lt;percent&gt;</code></td>
<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing
coverage of all activities within your package.</td>
</tr>
<tr>
<td><code>--pct-anyevent &lt;percent&gt;</code></td>
<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used
buttons on the device, and so forth.</td>
</tr>
<tr>
<td rowspan="2">Constraints</td>
<td><code>-p &lt;allowed-package-name&gt;</code></td>
<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system
to visit activities within those packages. If your application requires access to activities in
other packages (e.g. to select a contact) you'll need to specify those packages as well.
If you don't specify any packages, the Monkey will allow the system to launch activities
in all packages. To specify multiple packages, use the -p option multiple times &mdash; one -p
option per package.</td>
</tr>
<tr>
<td><code>-c &lt;main-category&gt;</code></td>
<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the
system to visit activities that are listed with one of the specified categories.
If you don't specify any categories, the Monkey will select activities listed with the category
Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c
option multiple times &mdash; one -c option per category.</td>
</tr>
<tr>
<td rowspan="8">Debugging</td>
<td><code>--dbg-no-events</code></td>
<td>When specified, the Monkey will perform the initial launch into a test activity, but
will not generate any further events.
For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey
running for 30 seconds or more. This provides an environment in which you can monitor package
transitions invoked by your application.</td>
</tr>
<tr>
<td><code>--hprof</code></td>
<td>If set, this option will generate profiling reports immediately before and after
the Monkey event sequence.
This will generate large (~5Mb) files in data/misc, so use with care. See
<a href="{@docRoot}guide/developing/tools/traceview.html" title="traceview">Traceview</a> for more information
on trace files.</td>
</tr>
<tr>
<td><code>--ignore-crashes</code></td>
<td>Normally, the Monkey will stop when the application crashes or experiences any type of
unhandled exception. If you specify this option, the Monkey will continue to send events to
the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-timeouts</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of timeout error such
as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to
send events to the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-security-exceptions</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of permissions error,
for example if it attempts to launch an activity that requires certain permissions. If you specify
this option, the Monkey will continue to send events to the system, until the count is
completed.</td>
</tr>
<tr>
<td><code>--kill-process-after-error</code></td>
<td>Normally, when the Monkey stops due to an error, the application that failed will be left
running. When this option is set, it will signal the system to stop the process in which the error
occurred.
Note, under a normal (successful) completion, the launched process(es) are not stopped, and
the device is simply left in the last state after the final event.</td>
</tr>
<tr>
<td><code>--monitor-native-crashes</code></td>
<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td>
</tr>
<tr>
<td><code>--wait-dbg</code></td>
<td>Stops the Monkey from executing until a debugger is attached to it.</td>
</tr>
</table>
<!-- TODO: add a section called "debugging" that covers ways to use it,
need to clear data, use of the seed, etc. -->
<!-- TODO: add a section that lays down a contract for Monkey output so it can be
scripted safely. -->
base/docs/html/guide/developing/tools/monkeyrunner_concepts.jd
+308
View File
@@ -0,0 +1,308 @@
page.title=monkeyrunner
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#SampleProgram">A Simple monkeyrunner Program</a>
</li>
<li>
<a href="#APIClasses">The monkeyrunner API</a>
</li>
<li>
<a href="#RunningMonkeyRunner">Running monkeyrunner</a>
</li>
<li>
<a href="#Help">monkeyrunner Built-in Help</a>
</li>
<li>
<a href="#Plugins">Extending monkeyrunner with Plugins</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>
</li>
</ol>
</div>
</div>
<p>
The monkeyrunner tool provides an API for writing programs that control an Android device
or emulator from outside of Android code. With monkeyrunner, you can write a Python program
that installs an Android application or test package, runs it, sends keystrokes to it,
takes screenshots of its user interface, and stores screenshots on the workstation. The
monkeyrunner tool is primarily designed to test applications and devices at the
functional/framework level and for running unit test suites, but you are free to use it for
other purposes.
</p>
<p>
The monkeyrunner tool is not related to the
<a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>,
also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an
<code><a href="{@docRoot}guide/developing/tools/adb.html">adb</a></code> shell directly on the
device or emulator and generates pseudo-random streams of user and system events. In comparison,
the monkeyrunner tool controls devices and emulators from a workstation by sending specific
commands and events from an API.
</p>
<p>
The monkeyrunner tool provides these unique features for Android testing:
</p>
<ul>
<li>
Multiple device control: The monkeyrunner API can apply one or more
test suites across multiple devices or emulators. You can physically attach all the devices
or start up all the emulators (or both) at once, connect to each one in turn
programmatically, and then run one or more tests. You can also start up an emulator
configuration programmatically, run one or more tests, and then shut down the emulator.
</li>
<li>
Functional testing: monkeyrunner can run an automated start-to-finish test of an Android
application. You provide input values with keystrokes or touch events, and view the results
as screenshots.
</li>
<li>
Regression testing - monkeyrunner can test application stability by running an application
and comparing its output screenshots to a set of screenshots that are known to be correct.
</li>
<li>
Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire
system of Python-based modules and programs for controlling Android devices. Besides using
the monkeyrunner API itself, you can use the standard Python
<code><a href="http://docs.python.org/library/os.html">os</a></code> and
<code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code>
modules to call Android tools such as
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.
<p>
You can also add your own classes to the monkeyrunner API. This is described
in more detail in the section
<a href="#Plugins">Extending monkeyrunner with plugins</a>.
</p>
</li>
</ul>
<p>
The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, a
implementation of Python that uses the Java programming language. Jython allows the
monkeyrunner API to interact easily with the Android framework. With Jython you can
use Python syntax to access the constants, classes, and methods of the API.
</p>
<h2 id="SampleProgram">A Simple monkeyrunner Program</h2>
<p>
Here is a simple monkeyrunner program that connects to a device, creating a
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>
object. Using the <code>MonkeyDevice</code> object, the program installs an Android application
package, runs one of its activities, and sends key events to the activity.
The program then takes a screenshot of the result, creating a
<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> object.
From this object, the program writes out a <code>.png</code> file containing the screenshot.
</p>
<pre>
# Imports the monkeyrunner modules used by this program
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice
# Connects to the current device, returning a MonkeyDevice object
device = MonkeyRunner.waitForConnection()
# Installs the Android package. Notice that this method returns a boolean, so you can test
# to see if the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')
# Runs an activity in the application
device.startActivity(component='com.example.android.myapplication.MainActivity')
# Presses the Menu button
device.press('KEYCODE_MENU','DOWN_AND_UP')
# Takes a screenshot
result = device.takeSnapShot
# Writes the screenshot to a file
result.writeToFile('myproject/shot1.png','png')
</pre>
<h2 id="APIClasses">The monkeyrunner API</h2>
<p>
The monkeyrunner API is contained in three modules in the package
<code>com.android.monkeyrunner</code>:
</p>
<ul>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html">MonkeyRunner</a></code>:
A class of utility methods for monkeyrunner programs. This class provides a method for
connecting monkeyrunner to a device or emulator. It also provides methods for
creating UIs for a monkeyrunner program and for displaying the built-in help.
</li>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>:
Represents a device or emulator. This class provides methods for installing and
uninstalling packages, starting an Activity, and sending keyboard or touch events to an
application. You also use this class to run test packages.
</li>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>:
Represents a screen capture image. This class provides methods for capturing screens,
converting bitmap images to various formats, comparing two MonkeyImage objects, and
writing an image to a file.
</li>
</ul>
<p>
In a Python program, you access each class as a Python module. The monkeyrunner tool
does not import these modules automatically. To import a module, use the
Python <code>from</code> statement:
</p>
<pre>
from com.android.monkeyrunner import &lt;module&gt;
</pre>
<p>
where <code>&lt;module&gt;</code> is the class name you want to import. You can import more
than one module in the same <code>from</code> statement by separating the module names with
commas.
</p>
<h2 id="RunningMonkeyRunner">Running monkeyrunner</h2>
<p>
You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in
an interactive session. You do both by invoking the <code>monkeyrunner</code> command
which is found in the <code>tools/</code> subdirectory of your SDK directory.
If you provide a filename as an argument, the <code>monkeyrunner</code> command
runs the file's contents as a Python program; otherwise, it starts an interactive session.
</p>
<p>
The syntax of the <code>monkeyrunner</code> command is
</p>
<pre>
monkeyrunner -plugin &lt;plugin_jar&gt; &lt;program_filename&gt; &lt;program_options&gt;
</pre>
<p>
Table 1 explains the flags and arguments.
</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p>
<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td>
<nobr>
<code>-plugin &lt;plugin_jar&gt;</code>
</nobr>
</td>
<td>
(Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner.
To learn more about monkeyrunner plugins, see
<a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one
file, include the argument multiple times.
</td>
</tr>
<tr>
<td>
<nobr>
<code>&lt;program_filename&gt;</code>
</nobr>
</td>
<td>
If you provide this argument, the <code>monkeyrunner</code> command runs the contents
of the file as a Python program. If the argument is not provided, the command starts an
interactive session.
</td>
</tr>
<tr>
<td>
<code>&lt;program_options&gt;</code>
</td>
<td>
(Optional) Flags and arguments for the program in &lt;program_file&gt;.
</td>
</tr>
</table>
<h2 id="Help">monkeyrunner Built-in Help</h2>
<p>
You can generate an API reference for monkeyrunner by running:
</p>
<pre>
monkeyrunner &lt;format&gt; help.py &lt;outfile&gt;
</pre>
<p>
The arguments are:
</p>
<ul>
<li>
<code>&lt;format&gt;</code> is either <code>text</code> for plain text output
or <code>html</code> for HTML output.
</li>
<li>
<code>&lt;outfile&gt;</code> is a path-qualified name for the output file.
</li>
</ul>
<h2 id="Plugins">Extending monkeyrunner with Plugins</h2>
<p>
You can extend the monkeyrunner API with classes you write in the Java programming language
and build into one or more <code>.jar</code> files. You can use this feature to extend the
monkeyrunner API with your own classes or to extend the existing classes. You can also use this
feature to initialize the monkeyrunner environment.
</p>
<p>
To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the
<code>-plugin &lt;plugin_jar&gt;</code> argument described in
<a href="#table1">table 1</a>.
</p>
<p>
In your plugin code, you can import and extend the the main monkeyrunner classes
<code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in
<code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>).
</p>
<p>
Note that plugins do not give you access to the Android SDK. You can't import packages
such as <code>com.android.app</code>. This is because monkeyrunner interacts with the
device or emulator below the level of the framework APIs.
</p>
<h3>The plugin startup class</h3>
<p>
The <code>.jar</code> file for a plugin can specify a class that is instantiated before
script processing starts. To specify this class, add the key
<code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> file's
manifest. The value should be the name of the class to run at startup. The following
snippet shows how you would do this within an <code>ant</code> build script:
</p>
<pre>
&lt;jar jarfile=&quot;myplugin&quot; basedir="&#36;&#123;build.dir&#125;&quot;&gt;
&lt;manifest&gt;
&lt;attribute name=&quot;MonkeyRunnerStartupRunner&quot; value=&quot;com.myapp.myplugin&quot;/&gt;
&lt;/manifest&gt;
&lt;/jar&gt;
</pre>
<p>
To get access to monkeyrunner's runtime environment, the startup class can implement
<code>com.google.common.base.Predicate&lt;PythonInterpreter&gt;</code>. For example, this
class sets up some variables in the default namespace:
</p>
<pre>
package com.android.example;
import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;
public class Main implements Predicate&lt;PythonInterpreter&gt; {
&#64;Override
public boolean apply(PythonInterpreter anInterpreter) {
/*
* Examples of creating and initializing variables in the monkeyrunner environment's
* namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
* and "use_emulator"
*
*/
anInterpreter.set("newtest", "enabled");
anInterpreter.set("use_emulator", 1);
return true;
}
}
</pre>
base/docs/html/guide/developing/tools/othertools.jd
+95
View File
@@ -0,0 +1,95 @@
page.title=Other Tools
@jd:body
<p>The sections below describe other tools that you can use when building
Android applications. </p>
<p>All of the tools are included in the Android SDK and are accessible from the
<code>&lt;sdk&gt;/tools/</code> directory.</p>
<h2>Contents</h2>
<dl>
<dt><a href="#android">android</a></dd>
<dt><a href="#mksdcard">mksdcard</a></dt>
<dt><a href="#dx">dx</a></dt>
</dl>
<a name="activitycreator"></a>
<h2 id="android">android</h2>
<p>{@code android} is an important development tool that lets you:</p>
<ul>
<li>Create, delete, and view Android Virtual Devices (AVDs). See
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</li>
<li>Create and update Android projects. See
<a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li>
<li>Update your Android SDK with new platforms, add-ons, and documentation. See
<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li>
</ul>
<p>If you develop in Eclipse with the ADT plugin, you can perform
these tasks directly from the IDE. To create
Android projects and AVDs from Eclipse, see <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing
In Eclipse</a>. To update your SDK from Eclipse, see
<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.
</p>
<a name="mksdcard"></a>
<h2>mksdcard</h2>
<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can
load in the emulator, to simulate the presence of an SD card in the device.
Here is the usage for mksdcard:</p>
<pre>mksdcard [-l label] &lt;size&gt;[K|M] &lt;file&gt;</pre>
<p>The table below lists the available options/arguments</p>
<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td><code>-l</code></td>
<td>A volume label for the disk image to create. </td>
</tr>
<tr>
<td><code>size</code></td>
<td>An integer that specifies the size (in bytes) of disk image to create.
You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to
&lt;size&gt;. For example, <code>1048576K</code>, <code>1024M</code>.</td>
</tr>
<tr>
<td><code>file</code></td>
<td>The path/filename of the disk image to create. </td>
</tr>
</table>
<p>Once you have created the disk image file, you can load it in the emulator at
startup using the emulator's -sdcard option. For more information, see
<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
<pre>emulator -sdcard &lt;file&gt;</pre>
<a name="dx"></a>
<h2>dx</h2>
<p>The dx tool lets you generate Android bytecode from .class files. The tool
converts target files and/or directories to Dalvik executable format (.dex) files,
so that they can run in the Android environment. It can also dump the class files
in a human-readable format and run a target unit test. You can get the usage and
options for this tool by using <code>dx --help</code>.</p>
base/docs/html/guide/developing/tools/proguard.jd
+187
View File
@@ -0,0 +1,187 @@
page.title=ProGuard
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#enabling">Enabling ProGuard</a></li>
<li><a href="#configuring">Configuring ProGuard</a></li>
<li>
<a href="#decoding">Decoding Obfuscated Stack Traces</a>
<ol>
<li><a href="#considerations">Debugging considerations for published
applications</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
Manual</a></li>
<li><a href="http://proguard.sourceforge.net/manual/retrace/introduction.html">ProGuard
ReTrace Manual</a></li>
</ol>
</div>
</div>
<p>The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and
renaming classes, fields, and methods with semantically obscure names. The result is a smaller
sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your
application harder to reverse engineer, it is important that you use it
when your application utilizes features that are sensitive to security like when you are
<a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p>
<p>ProGuard is integrated into the Android build system, so you do not have to invoke it
manually. ProGuard runs only when you build your application in release mode, so you do not
have to deal with obfuscated code when you build your application in debug mode.
Having ProGuard run is completely optional, but highly recommended.</p>
<p>This document describes how to enable and configure ProGuard as well as use the
<code>retrace</code> tool to decode obfuscated stack traces.</p>
<h2 id="enabling">Enabling ProGuard</h2>
<p>When you create an Android project, a <code>proguard.cfg</code> file is automatically
generated in the root directory of the project. This file defines how ProGuard optimizes and
obfuscates your code, so it is very important that you understand how to customize it for your
needs. The default configuration file only covers general cases, so you most likely have to edit
it for your own needs. See the following section about <a href="#configuring">Configuring ProGuard</a> for information on
customizing the ProGuard configuration file.</p>
<p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the
<code>proguard.config</code> property in the <code>&lt;project_root&gt;/default.properties</code>
file. The path can be an absolute path or a path relative to the project's root.</p>
<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory),
you can specify its location like this:</p>
<pre class="no-pretty-print">
proguard.config=proguard.cfg
</pre>
<p>
You can also move the the file to anywhere you want, and specify the absolute path to it:
</p>
<pre class="no-pretty-print">
proguard.config=/path/to/proguard.cfg
</pre>
<p>When you build your application in release mode, either by running <code>ant release</code> or
by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if
the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes
the application's bytecode before packaging everything into an <code>.apk</code> file. Building in debug mode
does not invoke ProGuard, because it makes debugging more cumbersome.</p>
<p>ProGuard outputs the following files after it runs:</p>
<dl>
<dt><code>dump.txt</code></dt>
<dd>Describes the internal structure of all the class files in the <code>.apk</code> file</dd>
<dt><code>mapping.txt</code></dt>
<dd>Lists the mapping between the original and obfuscated class, method, and field names.
This file is important when you receive a bug report from a release build, because it
translates the obfuscated stack trace back to the original class, method, and member names.
See <a href="#decoding">Decoding Obfuscated Stack Traces</a> for more information.</dd>
<dt><code>seeds.txt</code></dt>
<dd>Lists the classes and members that are not obfuscated</dd>
<dt><code>usage.txt</code></dt>
<dd>Lists the code that was stripped from the <code>.apk</code></dd>
</ul>
<p>These files are located in the following directories:</p>
<ul>
<li><code>&lt;project_root&gt;/bin/proguard</code> if you are using Ant.</li>
<li><code>&lt;project_root&gt;/proguard</code> if you are using Eclipse.</li>
</ul>
<p class="caution"><strong>Caution:</strong> Every time you run a build in release mode, these files are
overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your
application in order to de-obfuscate bug reports from your release builds.
For more information on why saving these files is important, see
<a href="#considerations">Debugging considerations for published applications</a>.
</p>
<h2 id="configuring">Configuring ProGuard</h2>
<p>For some situations, the default configurations in the <code>proguard.cfg</code> file will
suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code
that it thinks is not used, but your application actually needs. Some examples include:</p>
<ul>
<li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li>
<li>a method called from JNI</li>
<li>dynamically referenced fields and methods</li>
</ul>
<p>The default <code>proguard.cfg</code> file tries to cover general cases, but you might
encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard
strips away an entire class that your application calls.</p>
<p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in
the <code>proguard.cfg</code> file. For example:</p>
<pre>
-keep public class &lt;MyClass&gt;
</pre>
<p>There are many options and considerations when using the <code>-keep</code> option, so it is
highly recommended that you read the <a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
Manual</a> for more information about customizing your configuration file. The <a href=
"http://proguard.sourceforge.net/manual/usage.html#keepoverview">Overview of Keep options</a> and
<a href="http://proguard.sourceforge.net/index.html#/manual/examples.html">Examples section</a>
are particularly helpful. The <a href=
"http://proguard.sourceforge.net/manual/troubleshooting.html">Troubleshooting</a> section of the
ProGuard Manual outlines other common problems you might encounter when your code gets stripped
away.</p>
<h2 id="decoding">Decoding Obfuscated Stack Traces</h2>
<p>When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes
debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a
<code>&lt;project_root&gt;/bin/proguard/mapping.txt</code> file, which shows you the original
class, method, and field names mapped to their obfuscated names.</p>
<p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux
or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the
<code>&lt;sdk_root&gt;/tools/proguard/</code> directory. The syntax for executing the
<code>retrace</code> tool is:</p>
<pre>retrace.bat|retrace.sh [-verbose] mapping.txt [&lt;stacktrace_file&gt;]</pre>
<p>For example:</p>
<pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre>
<p>If you do not specify a value for <em>&lt;stacktrace_file&gt;</em>, the <code>retrace</code> tool reads
from standard input.</p>
<h3 id="considerations">Debugging considerations for published applications</h3>
<p>Save the <code>mapping.txt</code> file for every release that you publish to your users.
By retaining a copy of the <code>mapping.txt</code> file for each release build,
you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace.
A project's <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be
careful about saving the versions that you need.</p>
<p>For example, say you publish an application and continue developing new features of
the application for a new version. You then do a release build using ProGuard soon after. The
build overwrites the previous <code>mapping.txt</code> file. A user submits a bug report
containing a stack trace from the application that is currently published. You no longer have a way
of debugging the user's stack trace, because the <code>mapping.txt</code> file associated with the version
on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so
ensure that you save a copy for every release that you anticipate you have to debug.</p>
<p>How you save the <code>mapping.txt</code> file is your decision. For example, you can rename them to
include a version or build number, or you can version control them along with your source
code.</p>
base/docs/html/guide/developing/tools/traceview.jd
+319
View File
@@ -0,0 +1,319 @@
page.title=Traceview: A Graphical Log Viewer
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#creatingtracefiles">Creating Trace Files</a></li>
<li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li>
<li><a href="#runningtraceview">Viewing Trace Files in Traceview</a>
<ol>
<li><a href="#timelinepanel">Timeline Panel</a></li>
<li><a href="#profilepanel">Profile Panel</a></li>
</ol></li>
<li><a href="#format">Traceview File Format</a>
<ol>
<li><a href="#datafileformat">Data File Format</a></li>
<li><a href="#keyfileformat">Key File Format</a></li>
</ol></li>
<li><a href="#knownissues">Traceview Known Issues</a></li>
<li><a href="#dmtracedump">Using dmtracedump</a></li>
</ol>
</div>
</div>
<p>Traceview is a graphical viewer for execution logs
saved by your application. Traceview can help you debug your application and
profile its performance. The sections below describe how to use the program. </p>
<a name="creatingtracefiles"></a>
<h2>Creating Trace Files</h2>
<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug}
class in your code and call its methods to start and stop logging of trace information
to disk. When your application quits, you can then use Traceview to examine the log files
for useful run-time information such
as method calls and run times. </p>
<p>To create the trace files, include the {@link android.os.Debug} class and call one
of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods.
In the call, you specify a base name for the trace files that the system generates.
To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}.
These methods start and stop method tracing across the entire virtual machine. For
example, you could call startMethodTracing() in your activity's onCreate()
method, and call stopMethodTracing() in that activity's onDestroy() method.</p>
<pre>
// start tracing to "/sdcard/calc.trace"
Debug.startMethodTracing("calc");
// ...
// stop tracing
Debug.stopMethodTracing();
</pre>
<p>When your application calls startMethodTracing(), the system creates a
file called <code>&lt;trace-base-name>.trace</code>. This contains the
binary method trace data and a mapping table with thread and method names.</p>
<p>The system then begins buffering the generated trace data, until your application calls
stopMethodTracing(), at which time it writes the buffered data to the
output file.
If the system reaches the maximum buffer size before stopMethodTracing()
is called, the system stops tracing and sends a notification
to the console. </p>
<p>Interpreted code will run more slowly when profiling is enabled. Don't
try to generate absolute timings from the profiler results (i.e. "function
X takes 2.5 seconds to run"). The times are only
useful in relation to other profile output, so you can see if changes
have made the code faster or slower. </p>
<p>When using the Android emulator, you must create an SD card image upon which
the trace files will be written. For example, from the <code>/tools</code> directory, you
can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p>
<pre>
<b>$</b> mksdcard 1024M ./imgcd
<b>$</b> emulator -sdcard ./imgcd
</pre>
<p>For more information, read about the
<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p>
<p>The format of the trace files is described <a href="#format">later
in this document</a>. </p>
<a name="copyingfiles"></a>
<h2>Copying Trace Files to a Host Machine</h2>
<p>After your application has run and the system has created your trace files <code>&lt;trace-base-name>.trace</code>
on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy
the files. Here's an example that shows how to copy an example file,
calc.trace, from the default location on the emulator to the /tmp directory on
the emulator host machine:</p>
<pre>adb pull /sdcard/calc.trace /tmp</pre>
<a name="runningtraceview"></a>
<h2>Viewing Trace Files in Traceview</h2>
<p>To run traceview and view the trace files, enter <code>traceview &lt;trace-base-name></code>.
For example, to run Traceview on the example files copied in the previous section,
you would use: </p>
<pre>traceview /tmp/calc</pre>
<p>Traceview loads the log files and displays their data in a window that has two panels:</p>
<ul>
<li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread
and method started and stopped</li>
<li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li>
</ul>
<p>The sections below provide addition information about the traceview output panes. </p>
<a name="timelinepanel"></a>
<h3>Timeline Panel </h3>
<p>The image below shows a close up of the timeline panel. Each thread&rsquo;s
execution is shown in its own row, with time increasing to the right. Each method
is shown in another color (colors are reused in a round-robin fashion starting
with the methods that have the most inclusive time). The thin lines underneath
the first row show the extent (entry to exit) of all the calls to the selected
method. The method in this case is LoadListener.nativeFinished() and it was
selected in the profile view. </p>
<p><img src="/images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p>
<a name="profilepanel"></a>
<h3>Profile Panel</h3>
<p>The image below shows the profile pane. The profile pane shows a
summary of all the time spent in a method. The table shows
both the inclusive and exclusive times (as well as the percentage of the total
time). Exclusive time is the time spent in the method. Inclusive time is the
time spent in the method plus the time spent in any called functions. We refer
to calling methods as &quot;parents&quot; and called methods as &quot;children.&quot;
When a method is selected (by clicking on it), it expands to show the parents
and children. Parents are shown with a purple background and children
with a yellow background. The last column in the table shows the number of calls
to this method plus the number of recursive calls. The last column shows the
number of calls out of the total number of calls made to that method. In this
view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking
at the timeline panel shows that one of those calls took an unusually
long time.</p>
<p><img src="/images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p>
<a name="format"></a>
<h2>Traceview File Format</h2>
<p>Tracing creates two distinct pieces of output: a <em>data</em> file,
which holds the trace data, and a <em>key</em> file, which
provides a mapping from binary identifiers to thread and method names.
The files are concatenated when tracing completes, into a
single <em>.trace</em> file. </p>
<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate
these files for you. If you have old key and data files that you'd still like to trace, you
can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p>
<a name="datafileformat"></a>
<h3>Data File Format</h3>
<p>The data file is binary, structured as
follows (all values are stored in little-endian order):</p>
<pre>* File format:
* header
* record 0
* record 1
* ...
*
* Header format:
* u4 magic 0x574f4c53 ('SLOW')
* u2 version
* u2 offset to data
* u8 start date/time in usec
*
* Record format:
* u1 thread ID
* u4 method ID | method action
* u4 time delta since start, in usec
</pre>
<p>The application is expected to parse all of the header fields, then seek
to &quot;offset to data&quot; from the start of the file. From there it just
reads
9-byte records until EOF is reached.</p>
<p><em>u8 start date/time in usec</em> is the output from gettimeofday().
It's mainly there so that you can tell if the output was generated yesterday
or three months ago.</p>
<p><em>method action</em> sits in the two least-significant bits of the
<em>method</em> word. The currently defined meanings are: </p>
<ul>
<li>0 - method entry </li>
<li>1 - method exit </li>
<li>2 - method &quot;exited&quot; when unrolled by exception handling </li>
<li>3 - (reserved)</li>
</ul>
<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.
</p>
<a name="keyfileformat"></a>
<h3>Key File Format</h3>
<p>The key file is a plain text file divided into three sections. Each
section starts with a keyword that begins with '*'. If you see a '*' at the start
of a line, you have found the start of a new section.</p>
<p>An example file might look like this:</p>
<pre>*version
1
clock=global
*threads
1 main
6 JDWP Handler
5 Async GC
4 Reference Handler
3 Finalizer
2 Signal Handler
*methods
0x080f23f8 java/io/PrintStream write ([BII)V
0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V
0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V
0x080da620 java/lang/RuntimeException &lt;init&gt; ()V
[...]
0x080f630c android/os/Debug startMethodTracing ()V
0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V
*end</pre>
<dl>
<dt><em>version section</em></dt>
<dd>The first line is the file version number, currently
1.
The second line, <code>clock=global</code>, indicates that we use a common
clock across all threads. A future version may use per-thread CPU time counters
that are independent for every thread.</dd>
<dt><em>threads section</em></dt>
<dd>One line per thread. Each line consists of two parts: the thread ID, followed
by a tab, followed by the thread name. There are few restrictions on what
a valid thread name is, so include everything to the end of the line.</dd>
<dt><em>methods section </em></dt>
<dd>One line per method entry or exit. A line consists of four pieces,
separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB]
<em>method-name</em> [TAB]
<em>signature</em> . Only
the methods that were actually entered or exited are included in the list.
Note that all three identifiers are required to uniquely identify a
method.</dd>
</dl>
<p>Neither the threads nor methods sections are sorted.</p>
<a name="knownissues"></a>
<h2>Traceview Known Issues</h2>
<dl>
<dt>Threads</dt>
<dd>Traceview logging does not handle threads well, resulting in these two problems:
<ol>
<li> If a thread exits during profiling, the thread name is not emitted; </li>
<li>The VM reuses thread IDs. If a thread stops and another starts, they
may get the same ID. </li>
</ol>
</dd>
<a name="dmtracedump"></a>
<h2>Using dmtracedump</h2>
<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way
of generating graphical call-stack diagrams from trace log files. The tool
uses the Graphviz Dot utility to create the graphical output, so you need to
install Graphviz before running dmtracedump.</p>
<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call
represented as a node. It shows call flow (from parent node to child nodes) using
arrows. The diagram below shows an example of dmtracedump output.</p>
<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/>
<p style="margin-top:1em;">For each node, dmtracedump shows <code>&lt;ref> <em>callname</em> (&lt;inc-ms>,
&lt;exc-ms>,&lt;numcalls>)</code>, where</p>
<ul>
<li><code>&lt;ref></code> -- Call reference number, as used in trace logs</li>
<li><code>&lt;inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li>
<li><code>&lt;exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li>
<li><code>&lt;numcalls></code> -- Number of calls</li>
</ul>
<p>The usage for dmtracedump is: </p>
<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] &lt;trace-base-name></pre>
<p>The tool then loads trace log data from &lt;trace-base-name>.data and &lt;trace-base-name>.key.
The table below lists the options for dmtracedump.</p>
<table>
<tr>
<th>Option</td>
<th>Description</th>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name> </code></td>
<td>Diff with this trace name</td>
</tr>
<tr>
<td><code>-g&nbsp;&lt;outfile> </code></td>
<td>Generate output to &lt;outfile></td>
</tr>
<tr>
<td><code>-h </code></td>
<td>Turn on HTML output</td>
</tr>
<tr>
<td><code>-o </code></td>
<td>Dump the trace file instead of profiling</td>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name> </code></td>
<td>URL base to the location of the sortable javascript file</td>
</tr>
<tr>
<td><code>-t&nbsp;&lt;percent> </code></td>
<td>Minimum threshold for including child nodes in the graph (child's inclusive
time as a percentage of parent inclusive time). If this option is not used,
the default threshold is 20%. </td>
</tr>
</table>
base/docs/html/guide/developing/tools/zipalign.jd
+65
View File
@@ -0,0 +1,65 @@
page.title=zipalign
@jd:body
<p>zipalign is an archive alignment tool that provides important
optimization to Android application (.apk) files.
The purpose is to ensure that all uncompressed data starts
with a particular alignment relative to the start of the file. Specifically,
it causes all uncompressed data within the .apk, such as images or raw files,
to be aligned on 4-byte boundaries. This
allows all portions to be accessed directly with {@code mmap()} even if they
contain binary data with alignment restrictions.
The benefit is a reduction in the amount of RAM consumed
when running the application.</p>
<p>This tool should always be used to align your .apk file before
distributing it to end-users. The Android build tools can handle
this for you. When using Eclipse with the ADT plugin, the Export Wizard
will automatically zipalign your .apk after it signs it with your private key.
The build scripts used
when compiling your application with Ant will also zipalign your .apk,
as long as you have provided the path to your keystore and the key alias in
your project {@code build.properties} file, so that the build tools
can sign the package first.</p>
<p class="caution"><strong>Caution:</strong> zipalign must only be performed
<strong>after</strong> the .apk file has been signed with your private key.
If you perform zipalign before signing, then the signing procedure will undo
the alignment. Also, do not make alterations to the aligned package.
Alterations to the archive, such as renaming or deleting entries, will
potentially disrupt the alignment of the modified entry and all later
entries. And any files added to an "aligned" archive will not be aligned.</p>
<p>The adjustment is made by altering the size of
the "extra" field in the zip Local File Header sections. Existing data
in the "extra" fields may be altered by this process.</p>
<p>For more information about how to use zipalign when building your
application, please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing
Your Application</a>.</p>
<h3>Usage</h3>
<p>To align {@code infile.apk} and save it as {@code outfile.apk}:</p>
<pre>zipalign [-f] [-v] &lt;alignment> infile.apk outfile.apk</pre>
<p>To confirm the alignment of {@code existing.apk}:</p>
<pre>zipalign -c -v &lt;alignment> existing.apk</pre>
<p>The {@code &lt;alignment>} is an integer that defines the byte-alignment boundaries.
This must always be 4 (which provides 32-bit alignment) or else it effectively
does nothing.</p>
<p>Flags:</p>
<ul>
<li>{@code -f} : overwrite existing outfile.zip</li>
<li>{@code -v} : verbose output</li>
<li>{@code -c} : confirm the alignment of the given file</li>
</ul>