Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Docs: Removing most of the Eclipse ADT documentation from DAC." into mnc-docs

Browse Source
This commit is contained in:
David Friedman
2015-12-17 01:25:20 +00:00
committed by Android (Google) Code Review
parent 4360a3c3f7 49741566c2
commit ffb90fdeeb
10 changed files with 25 additions and 2227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
docs/html/sdk/installing/installing-adt.jd
View File

@@ -1,160 +0,0 @@
page.title=Installing the Eclipse Plugin
adt.zip.version=23.0.6
adt.zip.download=ADT-23.0.6.zip
adt.zip.bytes=103344298
adt.zip.checksum=f64b7e50c84799f41c642218c35f1bbe
@jd:body
<p class="caution">
<strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse is ending,
per our <a href=
"http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html"
class="external-link">announcement</a>. You should migrate your app development projects to
Android Studio as soon as possible. For more information on transitioning to Android Studio, see
<a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>.
</p>
<p>Android offers a custom plugin for the Eclipse IDE, called Android
Development Tools (ADT). This plugin provides a powerful, integrated
environment in which to develop Android apps. It extends the capabilities
of Eclipse to let you quickly set up new Android projects, build an app
UI, debug your app, and export signed (or unsigned) app packages (APKs) for distribution.
</p>
<p>You should install the ADT plugin
only if you already have an Eclipse installation that you want to continue using.
Your existing Eclipse installation must meet these requirements:</p>
<ul>
<li><a href="http://eclipse.org/mobile/">Eclipse</a> 3.7.2 (Indigo) or greater
<p class="note"><strong>Note:</strong> Eclipse 3.6 (Helios) is no longer
supported with the latest version of ADT.</p></li>
<li>Eclipse <a href="http://www.eclipse.org/jdt">JDT</a> plugin (included
in most Eclipse IDE packages) </li>
<li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK 6</a>
(JRE alone is not sufficient)</li>
<li><strong>Not</strong> compatible with GNU Compiler for Java (gcj)</li>
</ul>
<h2 id="Download">Download the ADT Plugin</h2>
<p>To add the ADT plugin to Eclipse:</p>
<ol>
<li>Start Eclipse, then select <strong>Help</strong> &gt; <strong>Install New
Software</strong>.</li>
<li>Click <strong>Add</strong>, in the top-right corner.</li>
<li>In the Add Repository dialog that appears, enter "ADT Plugin" for the <em>Name</em> and the
following URL for the <em>Location</em>:
<pre>https://dl-ssl.google.com/android/eclipse/</pre>
<p class="note"><strong>Note:</strong> The Android Developer Tools update site requires
a secure connection. Make sure the update site URL you enter starts with HTTPS.</p>
</li>
<li>Click <strong>OK</strong>.</li>
<li>In the Available Software dialog, select the checkbox next to Developer Tools and click
<strong>Next</strong>.</li>
<li>In the next window, you'll see a list of the tools to be downloaded. Click
<strong>Next</strong>. </li>
<li>Read and accept the license agreements, then click <strong>Finish</strong>.
<p>If you get a security warning saying that the authenticity or validity of
the software can't be established, click <strong>OK</strong>.</p></li>
<li>When the installation completes, restart Eclipse. </li>
</ol>
<h2 id="Configure">Configure the ADT Plugin</h2>
<p>Once Eclipse restarts, you
must specify the location of your Android SDK directory:</p>
<ol>
<li>In the "Welcome to Android Development" window that appears, select <strong>Use
existing SDKs</strong>.</li>
<li>Browse and select the location of the Android SDK directory you recently
downloaded and unpacked.</li>
<li>Click <strong>Next</strong>.</li>
</ol>
<p>Your Eclipse IDE is now set up to develop Android apps, but you need to add
the latest SDK platform tools and an Android platform to your environment.
To get these packages for your SDK, continue to
<a href="{@docRoot}sdk/installing/adding-packages.html">Adding Platforms and Packages</a>.</p>
<h2 id="Troubleshooting">Troubleshooting ADT Installation</h2>
<p>If you are having trouble downloading the ADT plugin after following the
steps above and you are behind a firewall (such as a corporate firewall), make sure that
you have properly configured your proxy settings in Eclipse. In Eclipse,
you can configure proxy information from the main Eclipse menu in
<strong>Window</strong> (on Mac OS X, <strong>Eclipse</strong>) &gt;
<strong>Preferences</strong> &gt; <strong>General</strong> &gt; <strong>Network
Connections</strong>.
</p>
<p>If you are still unable to use Eclipse to download the ADT plugin as a
remote update site, you can download the ADT zip file to your local machine and
manually install it:</p>
<ol>
<li>Download the ADT Plugin zip file (do not unpack it):
<table class="download">
<tr>
<th>Package</th>
<th>Size</th>
<th>MD5 Checksum</th>
</tr>
<tr>
<td>
<a href="https://dl.google.com/android/{@adtZipDownload}">{@adtZipDownload}</a>
</td>
<td>{@adtZipBytes} bytes</td>
<td>{@adtZipChecksum}</td>
</tr>
</table>
</li>
</li>
<li>Start Eclipse, then select <strong>Help</strong> &gt; <strong>Install New
Software</strong>.</li>
<li>Click <strong>Add</strong>, in the top-right corner.</li>
<li>In the Add Repository dialog, click <strong>Archive</strong>.</li>
<li>Select the downloaded {@adtZipDownload} file and click <strong>OK</strong>.</li>
<li>Enter "ADT Plugin" for the name and click <strong>OK</strong>.
<li>In the Available Software dialog, select the checkbox next to Developer Tools and click
<strong>Next</strong>.</li>
<li>In the next window, you'll see a list of the tools to be downloaded. Click
<strong>Next</strong>. </li>
<li>Read and accept the license agreements, then click <strong>Finish</strong>.
<p>If you get a security warning saying that the authenticity or validity of
the software can't be established, click <strong>OK</strong>.</p></li>
<li>When the installation completes, restart Eclipse. </li>
</ol>
<p>To update your plugin once you've installed using the zip file, you will have
to follow these steps again instead of the default update instructions.</p>
<h4>Other install errors</h4>
<p>Note that there are features of ADT that require some optional
Eclipse packages (for example, WST). If you encounter an error when
installing ADT, your Eclipse installation might not include these packages.
For information about how to quickly add the necessary packages to your
Eclipse installation, see the troubleshooting topic
<a href="{@docRoot}resources/faq/troubleshooting.html#installeclipsecomponents">ADT
Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p>
<h4>For Linux users</h4>
<p>If you encounter this error when installing the ADT Plugin for Eclipse:
<pre>
An error occurred during provisioning.
Cannot connect to keystore.
JKS</pre>
<p>
...then your development machine lacks a suitable Java VM. Installing Sun
Java 6 will resolve this issue and you can then reinstall the ADT
Plugin.</p>

2
docs/html/sdk/installing/migrate.jd
View File

@@ -1,4 +1,4 @@
page.title=Migrating to Android Studio
page.title=Migrating from Eclipse ADT
@jd:body

389
docs/html/tools/building/building-cmdline-ant.jd
View File

@@ -1,389 +0,0 @@
page.title=Building and Running from the Command Line
parent.title=Building and Running
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#DebugMode">Building in Debug Mode</a></li>
<li><a href="#ReleaseMode">Building in Release Mode</a>
<ol>
<li><a href="#ManualReleaseMode">Build unsigned</a></li>
<li><a href="#AutoReleaseMode">Build signed and aligned</a></li>
<li><a href="#OnceBuilt">Once built and signed in release mode</a></li>
</ol>
</li>
<li><a href="#RunningOnEmulator">Running on the Emulator</a></li>
<li><a href="#RunningOnDevice">Running on a Device</a></li>
<li><a href="#Signing">Application Signing</a></li>
<li><a href="#AntReference">Ant Command Reference</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from
the Command Line</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">Using the Android
Emulator</a></li>
<li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li>
</ol>
</div>
</div>
<p class="caution">
<strong>Important:</strong> Support for Ant as a build tool for Android is ending, per our
<a href="http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html"
class="external-link">announcement</a>. You should migrate your app development projects to
Android Studio and Gradle as soon as possible. For more information on transitioning to these
tools, see <a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>.
</p>
<p>There are two ways to build your application using the Ant build script: 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>. Regardless of which way you build your application,
it must be signed before it can install on an emulator or device&mdash;with a debug key when building
in debug mode and with your own private key when building in release mode.</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 you can install on an 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 onto an emulator or attached
development device. You cannot distribute an application that is signed with a debug key.
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}tools/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:
<pre>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;</pre>
<p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p>
<pre>c:\java\jdk1.7</pre>
<h2 id="DebugMode">Building in Debug Mode</h2>
<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}.</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 <code>.apk</code> file inside the project <code>bin/</code> directory, named
<code>&lt;your_project_name&gt;-debug.apk</code>. The file is already signed with
the debug key and has been aligned with
<a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>.
</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=
"#RunningOnEmulator">Running on the Emulator</a>.</p>
<h2 id="ReleaseMode">Building in Release Mode</h2>
<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>
<h3 id="ManualReleaseMode">Build unsigned</h3>
<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}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.
You should test the final build on different devices or AVDs to ensure that it
runs properly on different platforms.</p>
<h3 id="AutoReleaseMode">Build signed and aligned</h3>
<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 ant.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}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>To specify your keystore and alias, open the project {@code ant.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 ant.properties} and aligned with {@code
zipalign}. It's ready for installation and distribution.</p>
<h3 id="OnceBuilt">Once built and signed in release mode</h3>
<p>Once you have signed your application with a private key, you can install and run it on an
<a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</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 &gt; Applications &gt; Unknown sources</em>.)</p>
<h2 id="RunningOnEmulator">Running on the Emulator</h2>
<p>Before you can run your application on the Android Emulator, you must <a href=
"{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p>
<p>To run your application:</p>
<ol>
<li>
<strong>Open the AVD Manager and launch a virtual device</strong>
<p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool
with the <code>avd</code> options:</p>
<pre>
android avd
</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>tools/</code> directory, install the {@code .apk} on the
emulator:</p>
<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 build your application.</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 AVD Manager. Sometimes when you install an application 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 4.0 (API Level 14) platform, you should create an
AVD for each platform equal to and greater than 4.0 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>
<h2 id="RunningOnDevice">Running on a Device</h2>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Enable <strong>USB debugging</strong> on your device.
<ul>
<li>On most devices running Android 3.2 or older, you can find the option under
<strong>Settings > Applications > Development</strong>.</li>
<li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>.
<p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
options</strong> is hidden by default. To make it available, go
to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
</li>
</ul>
</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}tools/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:</p>
<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}tools/help/android.html">android Tool</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li>
<li><a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (ADB)</li>
</ul>
<h2 id="Signing">Application Signing</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>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}tools/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="AntReference">Ant Command Reference</h2>
<dt><code>ant clean</code></dt>
<dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code>
(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a
test project, the tested project is also cleaned.</dd>
<dt><code>ant debug</code></dt>
<dd>Builds a debug package. Works on application, library, and test projects and compiles
dependencies as needed.</dd>
<dt id="emma"><code>ant emma debug</code></dt>
<dd>Builds a test project while building the tested project with instrumentation turned on.
This is used to run tests with code coverage enabled.</dd>
<dt><code>ant release</code></dt>
<dd>Builds a release package.</dd>
<dt><code>ant instrument</code>
</dt>
<dd>Builds an instrumented debug package. This is generally called automatically when building a
test project with code coverage enabled (with the <code>emma</code>
target)</dd>
<dt><code>ant &lt;build_target&gt; install</code></dt>
<dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd>
<dt><code>ant installd</code></dt>
<dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not
already built.</dd>
<dt><code>ant installr</code></dt>
<dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not
already built.</dd>
<dt><code>ant installt</code></dt>
<dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the
tested application. This fails if the <code>.apk</code> is not already built.</dd>
<dt><code>ant installi</code></dt>
<dd>Installs an already compiled instrumented package. This is generally not used manually as
it's called when installing a test package. This fails if the <code>.apk</code> is not already
built.</dd>
<dt><code>ant test</code></dt>
<dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be
previously installed.</dd>
<dt><code>ant debug installt test</code></dt>
<dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
runs the tests.</dd>
<dt><code>ant emma debug install test</code></dt>
<dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and
runs the tests with code coverage enabled.</dd>

176
docs/html/tools/building/building-eclipse.jd
View File

@@ -1,176 +0,0 @@
page.title=Building and Running from Eclipse with ADT
parent.title=Building and Running
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#RunningOnEmulatorEclipse">Running on an Emulator</a></li>
<li><a href="#RunningOnDeviceEclipse">Running on a Device</a></li>
<li><a href="#RunConfig">Creating a Run Configuration</a></li>
</ol>
</div>
</div>
<p>Eclipse and ADT provide an environment where most of the details of the build process are
hidden from you. By default, the build process constantly runs in the background as you make
changes to your project.</p>
<p>When Eclipse automatically builds your application, it enables debugging and signs the
<code>.apk</code> with a debug key, by default. When you run the application,
Eclipse invokes ADB and installs your application to a device or emulator, so you do not have to
manually perform these tasks. Since most of the build process is taken care of by Eclipse, the
following topics show you how to run an application, which will automatically build your
application as well.</p>
<p>To distribute your application, however, you must build your application in release mode and
sign the <code>.apk</code> file with your own private key.</p>
<p>This document shows you how to run your application on an emulator or a real device
from Eclipse&mdash;all of which is done using the debug version of your application.
For more information about how to sign your application with a private key for release, see <a href=
"{@docRoot}tools/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p>
<h2 id="RunningOnEmulatorEclipse">Running on the emulator</h2>
<p>Before you can run your application on the Android Emulator, you must <a href=
"{@docRoot}tools/devices/managing-avds.html">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 run 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 run 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 you run the application with the Debug option, the application will start in the "Waiting For Debugger" mode. Once the debugger
is attached, Eclipse opens the Debug perspective and starts the application's main activity. Otherwise, if you run the
application with the normal Run option, Eclipse installs the application on the device and launches the main activity.</p>
<p>To set or change the run configuration used for your project, use the run configuration
manager. See the section below about <a href="#RunConfig">Creating a Run Configuration</a> for more 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 4.0 (API Level 14) platform, you should create an
AVD for each platform equal to and greater than 4.0 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>
<h2 id="RunningOnDeviceEclipse">Running on a device</h2>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Ensure that your application is debuggable by setting the
<code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>
element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>
<li>Enable <strong>USB debugging</strong> on your device.
<ul>
<li>On most devices running Android 3.2 or older, you can find the option under
<strong>Settings > Applications > Development</strong>.</li>
<li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>.
<p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
options</strong> is hidden by default. To make it available, go
to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
</li>
</ul>
</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}tools/device.html">Using Hardware Devices</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 run configuration or even create a new one.</p>
<p>To create or modify a run configuration, refer to the Eclipse documentation on how to create Run configurations.
The following steps highlight the important things you need to do for an Android project:</p>
<ol>
<li>Open the run configuration manager from the Run Menu.</li>
<li>Expand the <strong>Android Application</strong> item and create a new configuration or open
an existing one.
</li>
<li>With the Run Configuration selected, adjust your desired run configuration settings:
<ul>
<li>In the Android tab, specify the Project and Activity to launch.
</li>
<li><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}tools/help/emulator.html">Android
Emulator</a> document.</p>
</li>
</ul>
</li>
</ol>
<h4 id="AutoAndManualTargetModes">Automatic and manual target modes</h4>
<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 there is an AVD that matches the build target of the
project, ADT chooses that AVD. If the AVD versions are newer than the build target of the project,
ADT chooses the oldest possible version of an AVD that meets the project's build target
requirement.</li>
<li>If there are no suitable AVDs, the application is not installed a console error warning tells
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>

67
docs/html/tools/debugging/debugging-projects.jd
View File

@@ -1,67 +0,0 @@
page.title=Debugging from Eclipse with ADT
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#tools">The Debug Perspective</a></li>
<li><a href="#toptips">The DDMS Perspective</a></li>
</ol>
</div>
</div>
<p>If you are developing in Eclipse with the ADT plugin, you can use the built-in Java Debugger,
along with DDMS, to debug your applications. To access the debugger and
DDMS, Eclipse displays the debugger and DDMS features as perspectives, which are customized
Eclipse views that display certain tabs and windows depending on the perspective that you are in.
Eclipse also takes care of starting the ADB host daemon for you, so you do not have to run this
manually.</p>
<h2>The Debug Perspective in Eclipse</h2>
<p>The Debug Perspective in Eclipse gives you access to the following tabs:</p>
<ul>
<li>Debug - Displays previously and currently debugged Android applications and its currently
running threads</li>
<li>Variables - When breakpoints are set, displays variable values during code execution</li>
<li>Breakpoints - Displays a list of the set breakpoints in your application code</li>
<li>LogCat - Allows you to view system log messages in real time. The LogCat tab is also
available in the DDMS perspective.</li>
</ul>
<p>You can access the Debug Perspective by clicking <strong>Window &gt; Open Perspective &gt;
Debug</strong>. Refer to the appropriate documentation for the Eclipse debugger for more
information.</p>
<h2>The DDMS Perspective</h2>
<p>The DDMS Perspective in Eclipse lets you access all of the features
of DDMS from within the Eclipse IDE. The following sections of DDMS are available to you:</p>
<ul>
<li>Devices - Shows the list of devices and AVDs that are connected to ADB.</li>
<li>Emulator Control - Lets you carry out device functions.</li>
<li>LogCat - Lets you view system log messages in real time.</li>
<li>Threads - Shows currently running threads within a VM.</li>
<li>Heap - Shows heap usage for a VM.</li>
<li>Allocation Tracker - Shows the memory allocation of objects.</li>
<li>File Explorer - Lets you explore the device's file system.</li>
</ul>
<p>To access the DDMS perspective, go to <strong>Window &gt; Open Perspective &gt;
DDMS</strong>. If DDMS does not appear, go to <strong>Window &gt; Open Perspective &gt; Other
...</strong> and select <strong>DDMS</strong> from the Open Perspective window that appears. For
more information on using DDMS, see <a href="ddms.html">Using the Dalvik Debug Monitor Server</a>.
</p>

539
docs/html/tools/help/adt.jd
View File

@@ -2,540 +2,23 @@ page.title=Android Developer Tools
page.tags=adt
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#tools">SDK Tools Integration</a></li>
<li><a href="#editors">Code Editors</a>
<ol>
<li><a href="#resource-linking">Resource linking enhancements</a></li>
</ol>
</li>
<li><a href="#graphical-editor">Graphical Layout Editor</a>
<ol>
<li><a href="#canvas">Canvas and outline view</a></li>
<li><a href="#palette">Palette</a></li>
<li><a href="#config-chooser">Configuration chooser</a></li>
</ol>
</li>
<li><a href="#refactoring">Layout Factoring Support</a></li>
<li><a href="#Updating">Updating the ADT Plugin</a></li>
</ol>
</div>
</div>
<p class="caution">
<strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse is ending,
<strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse has ended,
per our <a href=
"http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html"
class="external-link">announcement</a>. You should migrate your app development projects to
Android Studio as soon as possible. For more information on transitioning to Android Studio, see
<a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>.
<a href="{@docRoot}sdk/installing/migrate.html">Migrating from Eclipse ADT</a>.
</p>
<p>Android Developer Tools (ADT) is a plugin for Eclipse that provides a suite of
tools that are integrated with the Eclipse IDE. It offers you access to many features that help
you develop Android applications. ADT
provides GUI access to many of the command line SDK tools as well as a UI design tool for rapid
prototyping, designing, and building of your application's user interface.</p>
<p>Formerly the official IDE solution for Android development, Android Developer Tools (ADT)
is a plugin for Eclipse that provides GUI-based access to many of the command-line SDK tools,
along with a UI design tool for rapid prototyping, designing, and building of your app's
user interface.</p>
<p>If you still wish to use the ADT plugin for Eclipse, see
<a href="{@docRoot}sdk/installing/installing-adt.html">Installing Eclipse Plugin.</a>
</p>
<h2 id="tools">SDK Tools Integration</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Need help designing icons?</h2>
<p>The <a href="http://android-ui-utils.googlecode.com/hg/asset-studio/dist/index.html">Android
Asset Studio</a> is a web-based tool that lets you generate icons from existing images,
clipart, or text. It also generates the icons with different DPIs for different screen sizes and
types.</p>
</div>
</div>
<p>Many of the tools that you can start or run from the command line are integrated into ADT.
They include:</p>
<ul>
<li><a href="{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a>:
Allows you to profile your program's execution
(<strong>Window &gt; Open Perspective &gt; Traceview</strong>). </li>
<li><a href="{@docRoot}tools/help/android.html">android</a>: Provides access to
the Android SDK Manager and AVD Manager. Other <code>android</code> features such as creating or
updating projects (application and library) are integrated throughout the Eclipse IDE. </li>
<li><a href="{@docRoot}tools/debugging/debugging-ui.html#HierarchyViewer">Hierarchy
Viewer</a>: Allows you to visualize your application's view hierarchy to find inefficiencies
(<strong>Window &gt; Open Perspective &gt; Hierarchy Viewer</strong>).</li>
<li><a href="{@docRoot}tools/debugging/debugging-ui.html#pixelperfect">Pixel
Perfect</a>: Allows you to closely examine your UI to help with designing and building.
(<strong>Window &gt; Open Perspective &gt; Pixel Perfect</strong>).</li>
<li><a href="{@docRoot}tools/debugging/ddms.html">DDMS</a>: Provides
debugging features including: screen capturing, thread and heap information, and logcat
(<strong>Window &gt; Open Perspective &gt; DDMS</strong>).</li>
<li><a href="{@docRoot}tools/help/adb.html">adb</a>: Provides access to
a device from your development system. Some features of
<code>adb</code> are integrated into ADT such as project installation (Eclipse run menu),
file transfer, device enumeration, and logcat (DDMS). You must access the more advanced
features of <code>adb</code>, such as shell commands, from the command line.</li>
<li><a href="{@docRoot}tools/help/proguard.html">ProGuard</a>: Allows code obfuscation,
shrinking, and optimization. ADT integrates ProGuard as part of the build, if you <a href=
"{@docRoot}tools/help/proguard.html#enabling">enable it</a>.</li>
</ul>
<h2 id="editors">Code Editors</h2>
<p>In addition to Eclipse's standard editor features, ADT provides custom XML editors to help
you create and edit Android manifests, resources, menus, and layouts in a form-based or graphical
mode. Double-clicking on an XML file in Eclipse's package explorer opens the
appropriate XML editor.
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Google I/O Session Video</h2>
<p>View the segment on the <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=30m50s">XML editors</a> for more
information.</p>
</div>
</div>
<p class="note"><strong>Note:</strong> You can edit Android-specific XML files (such as a layout
or manifest) in both a graphical mode and also an XML markup mode. You can switch between
these modes with the pair of tabs at the bottom of each custom XML editor.</p>
<p>In addition, some special file types that don't have custom editors, such as drawables, animations,
and color files offer editing enhancements such as XML tag completion.</p>
<p>ADT provides the following custom, form-based XML editors:</p>
<dl>
<dt><strong>Graphical Layout Editor</strong></dt>
<dd>Edit and design your XML layout files with a drag and drop interface. The layout editor
renders your interface as well, offering you a preview as you design your layouts. This editor
is invoked when you open an XML file with a view declared (usually declared in
<code>res/layout</code>. For more information, see <a href="#graphical-editor">Graphical Layout
Editor</a>.</dd>
<dt><strong>Android Manifest Editor</strong></dt>
<dd>Edit Android manifests with a simple graphical interface. This editor is invoked
when you open an <code>AndroidManifest.xml</code> file.</dd>
<dt><strong>Menu Editor</strong></dt>
<dd>Edit menu groups and items with a simple graphical interface. This editor is
invoked when you open an XML file with a <code>&lt;menu&gt;</code> declared (usually located in
the <code>res/menu</code> folder).</dd>
<dt><strong>Resources Editor</strong></dt>
<dd>Edit resources with a simple graphical interface. This editor is invoked when
you open an XML file with a <code>&lt;resources&gt;</code> tag declared.</dd>
<dt><strong>XML Resources Editor</strong></dt>
<dd>Edit XML resources with a simple graphical interface. This editor is invoked
when you open an XML file.</dd>
</dl>
<h3 id="resource-linking">Resource linking enhancements</h3>
<p>In addition to the normal code editing features of Eclipse, ADT provides enhancements to the Android
development experience that allow you to quickly jump to declarations of various types of resources such
as strings or layout files. You can access these enhancements by holding down the control key and
clicking on the following items:
<ul>
<li>A resource identifier, such as <code>R.id.button1</code>, jumps
to the XML definition of the view.</li>
<li>A declaration in the <code>R.java</code> file, such as <code>public
static final int Button01=0x7f050000"</code>, jumps to the corresponding XML definition.</li>
<li>An activity or service definition in your manifest, such as
<code>&lt;activity android:name=".TestActivity"&gt;</code>, jumps to the corresponding Java class. You can
jump from an activity definition (or service definition) into the corresponding Java class.</li>
<li>You can jump to any value definition (e.g. <code>@string:foo</code>), regardless of
which XML file
"foo" is defined in.</li>
<li>Any file-based declaration, such as <code>@layout/bar</code>, opens the file.</li>
<li>Non-XML resources, such as <code>@drawable/icon</code>, launches
Eclipse's default application for the given file type, which in this case is an
image.</li>
<li><code>@android</code> namespace resources opens the resources found in
the SDK install area.</li>
<li>Custom views in XML layouts, such as <code>&lt;foo.bar.MyView&gt;&lt;/foo.bar.MyView&gt;</code>,
or <code>&lt;view class="foo.bar.MyView"&gt;</code>) jump to the corresponding custom view classes.</li>
<li>An XML attribute such as <code>@android:string/ok</code> or <code>android.R.string.id</code> in Java code
opens the file that declares the strings. The XML tab opens when doing this, not
the form-based editor.</li>
</ul>
<h2 id="graphical-editor">Graphical Layout Editor</h2>
<p>ADT provides many features to allow you to design and build your application's user interface.
Many of these features are in the graphical layout editor, which you can access by opening one of
your application's XML layout files in Eclipse.
<p>As with ADT, support for the <a href="http://ant.apache.org/"
class="external-link">Ant</a>
tool for building from the command line has ended.
<a href="{@docRoot}tools/building/plugin-for-gradle.html">Gradle</a> is now the supported method
of building Android apps.
</p>
<p>The graphical layout editor is the main screen that you use to visually design and build your
UI. It is split up into the following parts:</p>
<dl>
<dt><strong>Canvas</strong></dt>
<dd>In the middle of the editor is the canvas. It provides the rendered view of your
layout and supports dragging and dropping of UI widgets
directly from the palette. You can select the platform version used to render the items in
the canvas. Each platform version has its own look and feel, which might be the similar to or
radically different from another platform version. The canvas renders the appropriate look
and feel for the currently selected platform version.
This platform version does not need to be the same as the version that your
application targets.
<p>The canvas also provides
context-sensitive actions in the layout actions bar, such as adjusting layout margins and
orientation.
The layout actions bar displays available actions depending on the selected UI element in the
canvas.</p>
</dd>
<dt><strong>Outline</strong></dt>
<dd>On the right side of the editor is the outline view. It displays a hierarchical
view of your layout where you can do things such as reorder of views. The outline
view exposes similar functionality as the canvas but displays your layout in an ordered
list instead of a rendered preview.</dd>
<dt><strong>Palette</strong></dt>
<dd>On the left side of the editor is the palette. It provides a set of widgets that
you can drag onto the canvas. The palette shows rendered previews of the
widgets for easy lookup of desired UI widgets.</dd>
<dt><strong>Configuration Chooser</strong></dt>
<dd>At the top of the editor is the configuration chooser.
It provides options to change a layout's rendering mode or screen type.</dd>
</dl>
<img src="{@docRoot}images/layout_editor.png" alt="graphical layout editor screenshot"
height="500" id="layout-editor" name="layout-editor">
<p class="img-caption"><strong>Figure 1.</strong> Graphical layout editor</p>
<h3 id="canvas">Canvas and outline view</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Google I/O Session Video</h2>
<p>View the segment on the <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=7m16s">canvas and outline view</a> and the
<a href="http://www.youtube.com/watch?v=Oq05KqjXTvs#t=11m43s">layout actions bar</a>
for more information.
</p>
</div>
</div>
<p>The canvas is the area where you can drag and drop UI widgets from the palette to design your
layout. The canvas offers a rendered preview of your layout depending on factors such as the
selected platform version, screen orientation, and currently selected theme that you specify in
the <a href="#configuration-chooser">configuration chooser</a>. You can also drag and drop
items into the outline view, which displays your layout in a hierarchical list. The outline view
exposes much of the same functionality as the canvas but offers another method of organization
that is beneficial for ordering and quickly selecting items. When you right-click a specific item
in the canvas or outline view, you can access a context-sensitive menu that lets you modify the
following attributes of the layout or view:</p>
<dl>
<dt><strong>View and layout properties</strong></dt>
<dd>
When you right-click a view or layout in the canvas or outline view, it brings up a
context-sensitive menu that lets you set things such as:
<ul>
<li>ID of the view or layout</li>
<li>Text of the view</li>
<li>Layout width</li>
<li>Layout height</li>
<li>Properties such as alpha or clickable</li>
</ul>
</dd>
<dt><strong>Animation preview and creation</strong></dt>
<dd>
If your layout or view is animated, you can preview the animation directly in the canvas
(when you select Android 3.0 or later as the platform version in the configuration chooser).
Right-click an item in the canvas and select <strong>Play Animation</strong>. If
animation is not associated with item, an option is available in the menu to create one.
<p>View the segment on the <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=28m30s">animation features</a> for more
information.</p>
</dd>
<dt><strong>Extract as Include</strong></dt>
<dd>You can extract parts of a current layout into its own layout file,
which you can then include in any layout with a single line of XML. See <a href=
"#extract-as-include">Layout Refactoring Support</a> for more information.</dd>
</dl>
<h4>Other canvas features</h4>
<p>The canvas has additional features not available in the outline view:</p>
<ul>
<li>Edit views with the layout actions bar: The context-sensitive layout actions bar allows you to
edit how a view is laid out in your UI. The available actions depend on the currently
selected view and its parent layout. Some common actions include
toggling the fill mode of the view and specifying margins. For instance, if you select a
{@link android.widget.Button}
in a {@link android.widget.LinearLayout}, you see actions related to the {@link
android.widget.LinearLayout}, such as a toggle to switch
between horizontal and vertical layout, and a toggle to control whether its children are
aligned along their text baseline. You will also see toolbar actions to control the individual
layout attributes of the child, such as whether the child should stretch out to match its
parent's width and height, a dropdown action to set the child's layout gravity, a button to open
a margin editor, and a layout weight editor.</li>
<li>Edit a nested layout in its current context: If you are editing a layout
that includes another layout, you can edit the included layout in the layout that included
it.</li>
<li>Preview drag and drop location: When you drag and drop a UI widget onto the canvas, ruler
markers appear showing you the approximate location of the UI widget depending on the
type of layout, such as {@link android.widget.RelativeLayout} or {@link
android.widget.LinearLayout}.</li>
<li>Preview animations: You can preview view and layout animations when you select Android 2.1
or later for the platform version in the configuration bar.</li>
<li>Render layouts in real-time: Layouts are rendered as accurately as possible according to
the platform version, including the appropriate system and action bars.</li>
<li>Support for fragments: Fragments can be rendered in the same screen as the layout that
includes the fragments.</li>
</ul>
<img src="{@docRoot}images/canvas.png" alt="screenshot of the canvas" height="553">
<p class="img-caption"><strong>Figure 2.</strong> Canvas portion of the layout editor showing
a rendered preview of an application</p>
<img src=
"{@docRoot}images/layout_outline.png" alt="screenshot of the outline view" height="185">
<p class="img-caption"><strong>Figure 3.</strong> Outline view showing current layout's structure</p>
<h3 id="palette">Palette</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Google I/O Session Video</h2>
<p>View the segment on the <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=7m53s">palette</a> for more information.</p>
</div>
</div>
<p>The palette contains the UI widgets that you can drag and drop onto the canvas and add to your
layout. The pallete categorizes the widgets and shows rendered previews
for easier lookup. The main features of the palette include:</p>
<ul>
<li>Different modes of rendered previews include: icons only, icons and text, tiny previews,
small previews, and previews (rendered in real size). Previews are only available for layouts
rendered with the latest revisions of Android 2.1 (API Level 7) or later.</li>
<li>Custom views in your project or library projects are added under custom views
category.</li>
<li>Arrange UI widgets alphabetically or by category.</li>
</ul>
<img src="{@docRoot}images/palette.png" alt="palette screenshot" height="566">
<p class="img-caption"><strong>Figure 4.</strong> Palette showing available UI widgets</p>
<h3 id="config-chooser">Configuration chooser</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Google I/O Session Video</h2>
<p>View the segment on the <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=12m51s">configuration chooser</a> for more
information.</p>
</div>
</div>
<p>The configuration chooser allows you to create and configure different configurations of
a layout for different situations, such as one for landscape and one for portrait mode. You can
set the following options for each configuration of a layout:
</p>
<ul>
<li>Screen type combo box: Predefined screen settings for common device configurations. You
can also create your own by selecting <strong>Custom...</strong>.</li>
<li>Screen orientation combo box: Portrait or Landscape screen orientation.</li>
<li>Theme combo box: Predefined themes or a custom theme that you have created.</li>
<li>Platform combo box: Platform version used to render the canvas and palette as well as
displaying appropriate themes.</li>
<li>Custom layout combo boxes: The locale, dock, and time of day combo boxes let you select
different versions of the same layout depending on the device's current state. You can
create a new version of a layout with the <strong>Create</strong> button.</li>
</ul>
<img src="{@docRoot}images/layout_bar.png" alt=
"configuration chooser screenshot" height="50" id="configuration-chooser" name="configuration chooser">
<p class="img-caption"><strong>Figure 5.</strong> Configuration chooser</p>
<h2 id="refactoring">Layout Refactoring Support</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Google I/O Session Video</h2>
<p>View the segment on <a href=
"http://www.youtube.com/watch?v=Oq05KqjXTvs#t=18m00s">refactoring features</a> for a rundown
of the more important refactoring features.</p>
</div>
</div>
<p>In both the graphical and XML layout editor, there are many features that help you quickly
refactor your layouts. The following list describes the major refactoring support:</p>
<dl>
<dt><strong>Change layout</strong></dt>
<dd>This lets you change the layout on the fly and re-renders the canvas for you.
You can apply this refactoring to any layout and the layout is converted to the new type if
possible. In many cases, the opening and closing tags of the layout's XML element are changed
along with things such as ID attributes and their references. However, for some supported
types, ADT attempts to preserve the layout, such as changing a {@link
android.widget.LinearLayout} to a {@link android.widget.RelativeLayout}.</dd>
<dt><strong>Change widget</strong></dt>
<dd>This lets you select one or more widgets and converts them to a new widget type. In
addition to changing the element name, it also removes any
attributes that are not supported by the new widget type and adds in any mandatory attributes
required by the new widget type. If the current ID of a widget includes the
current widget type in its ID (such as a <code>&lt;Button&gt;</code> widget named
<code>"button1"</code>), then the ID is changed to match the new widget type and all
references are updated.</dd>
<dt id="extract-as-include"><strong>Extract as include</strong></dt>
<dd>This lets you extract views inside of an existing layout into their own separate layout
file. An <code>include</code> tag that points to the newly created layout file is inserted
into the existing layout file. Right-click the view or layout and select <strong>Extract as
Include...</strong>.</dd>
<dt><strong>Extract string</strong></dt>
<dd>Extract strings from either XML or Java files into their own separate resource file.</dd>
<dt><strong>Extract style</strong></dt>
<dd>Extract style-related attributes from a layout and define them in a new
<code>styles.xml</code> file. You can select multiple views and this refactoring extracts all
of the same styles into one style and assigns that style to all the views that use it.</dd>
<dt><strong>Wrap-in container</strong></dt>
<dd>This lets you select one or more sibling elements and wrap them in a new container. This
can be applied to the root element as well, in which case the namespace declaration attributes
will be transferred to the new root. This refactoring also transfers <code>layout_</code>
attribute references to the new root, For example, suppose you have a {@link android.widget.RelativeLayout}.
If other widgets have layout constraints pointing to your widget, wrapping the widget causes
these constraints to point to the parent instead.</dd>
<dt><strong>Quick Assistant</strong></dt>
<dd>Provides refactoring suggestions depending on the current context. Press
<strong>Ctrl-1</strong> (or <strong>Cmd-1</strong> on
Mac) in an editor, and Eclipse provides a list of possible refactorings depending on the
context. The Quick Assistant provides fast access to all of the above refactorings, where applicable.
For example, if you are editing an XML value and decide you want to extract it out
as a string, place the text cursor in the string and press Ctrl-1 to see the refactoring context
menu.</dd>
</dl>
<h2 id="Updating">Updating the ADT Plugin</h2>
<p>From time to time, a new revision of the ADT Plugin becomes available, with
new features and bug fixes. Generally, when a new revision of ADT is available,
you should update to it as soon as convenient. </p>
<p>In some cases, a new revision of ADT will have a dependency on a specific
revision of the Android SDK Tools. If such dependencies exist, you will need to
update the SDK Tools package of the SDK after installing the new revision of
ADT. To update the SDK Tools package, use the Android SDK Manager, as
described in <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</a>.</p>
<p>To learn about new features of each ADT revision and also any dependencies on
the SDK Tools, see the listings in the <a href="{@docRoot}tools/revisions/index.html">Revisions</a>
section. To determine the version currently installed, open the
Eclipse Installed Software window using <strong>Help</strong>
&gt; <strong>Software Updates</strong> and refer to the version listed for
"Android Development Tools".</p>
<p>Follow the steps below to check whether an update is available and, if so,
to install it. </p>
<ol>
<li>Select <strong>Help</strong> &gt; <strong>Check for Updates</strong>.
<p>If there are no updates available, a dialog will say so and you're done.</p></li>
<li>If there are updates available, select Android DDMS, Android Development Tools,
and Android Hierarchy Viewer, then click <strong>Next</strong>.</li>
<li>In the Update Details dialog, click <strong>Next</strong>.</li>
<li>Read and accept the license agreement and then click <strong>Finish</strong>.
This will download and install the latest version of Android DDMS and
Android Development Tools.</li>
<li>Restart Eclipse.</li>
</ol>
<p>If you encounter problems during the update, remove the existing ADT plugin from Eclipse, then
perform a fresh installation, using the instructions for <a
href="{@docRoot}sdk/installing/installing-adt.html">Installing the ADT
Plugin</a>.</p>

273
docs/html/tools/projects/projects-eclipse.jd
View File

@@ -1,273 +0,0 @@
page.title=Managing Projects from Eclipse with ADT
parent.title=Managing Projects
parent.link=index.html
@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="#SettingUpLibraryProject">Setting up a Library Project</a></li>
<li><a href="#ReferencingLibraryProject">Referencing a Library Project</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href=
"{@docRoot}tools/testing/testing_eclipse.html#CreateTestProjectEclipse">Testing
from Eclipse with ADT</a></li>
</ol>
</div>
</div>
<p>Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects
(Android project, Library project, and Test project):
<ul>
<li>An Android project contains all of the files and resources that are needed to build a project into
an .apk file for installation. You need to create an Android project for any application that you
want to eventually install on a device.</li>
<li>You can also designate an Android project as a library project, which allows it to be shared
with other projects that depend on it. Once an Android project is designated as a library
project, it cannot be installed onto a device.</li>
<li>Test projects extend JUnit test functionality to include Android specific functionality. For
more information on creating a test project, see <a href=
"{@docRoot}tools/testing/testing_eclipse.html">Testing from Eclipse with ADT</a>.</li>
</ul>
<h2 id="CreatingAProject">Creating an Android Project</h2>
<p>The ADT plugin provides a <em>New Project Wizard</em> 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 Application Project</strong>, and click
<strong>Next</strong>.</li>
<li>Enter the basic settings for the project:
<ul>
<li>Enter an <strong>Application Name</strong>. This name is used as the title of your
application launcher icon when it is installed on a device.</li>
<li>Enter a <strong>Project Name</strong>. This text is used as the name of the folder where
your project is created.</li>
<li>Enter a <strong>Package Name</strong>. This class package namespace creates the initial
package structure for your applications code files and is added as the
<a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a>
attribute in your application's
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android manifest file</a>.
This manifest value serves as the unique identifier for your application app when you
distribute it to users. The package name must follow the same rules as packages in the Java
programming language.</li>
<li>Select a <strong>Minimum Required SDK</strong>. This setting indicates the lowest
version of the Android platform that your application supports. This value sets the
<code>minSdkVersion</code> attribute in the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
element of your manifest file.</li>
<li>Select a <strong>Target SDK</strong>. This setting indicates the highest version of
Android with which you have tested with your application and sets the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
targetSdkVersion}</a> attribute in your application's' manifest file.
<p class="note"><strong>Note:</strong> You can change the target SDK 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
<strong>Project Build Target</strong>.</p>
</li>
<li>Select a <strong>Compile With</strong> API version. This setting specifies what version
of the SDK to compile your project against. We strongly recommend using the most recent
version of the API.</li>
<li>Select a <strong>Theme</strong>. This setting specifies which standard Android
<a href="{@docRoot}design/style/themes.html">visual style</a> is applied to your
application.</li>
<li>Click <strong>Next</strong>.</li>
</ul>
</li>
<li>In the <strong>Configure Project</strong> page, select the desired settings and click
<strong>Next</strong>. Leave the <strong>Create activity</strong> option checked so you can
start your application with some essential components.</li>
<li>In the <strong>Configure Launcher Icon</strong> page, create an icon and click
<strong>Next</strong>.</li>
<li>In the <strong>Create Activity</strong> page, select activity template and click
<strong>Next</strong>. For more information about Android code templates, see
<a href="{@docRoot}tools/projects/templates.html">Using Code Templates</a>.
</li>
<li>Click <strong>Finish</strong> and the wizard creates a new project according to the options
you have chosen.</li>
</ol>
<p class="note"><strong>Tip:</strong> You can also start the New Project Wizard by clicking the
<strong>New</strong> <img src="/images/tools/eclipse-new.png"
style="vertical-align:baseline;margin:0"> icon in the toolbar.</p>
<h2 id="SettingUpLibraryProject">Setting up a Library Project</h2>
<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.</p>
<p>To create a new library 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 Application Project</strong>, and click
<strong>Next</strong>.</li>
<li>Enter the basic settings for the project, including <strong>Application Name</strong>,
<strong>Project Name</strong>, <strong>Package Name</strong>, and SDK settings.</li>
<li>In the <strong>Configure Project</strong> page, select the <strong>Mark this project as a
library</strong> option to flag the project as a library.</li>
<li>Set the other options as desired and click <strong>Next</strong>.</li>
<li>Follow the instructions to complete the wizard and create a new library project.</li>
</ol>
<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 <strong>is Library</strong> checkbox, as shown in
the figure below.</p>
<img src= "{@docRoot}images/developing/adt-props-isLib.png">
<p class="img-caption"><strong>Figure 1.</strong> Marking a project as an Android library.</p>
<p>To set the a 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 <strong>Android</strong> properties
group in the left pane and locate the <strong>Library</strong> properties in the right pane.</li>
<li>Select the <strong>is Library</strong> check box and click <strong>Apply</strong>.</li>
<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>
<p>Once you create a library project or mark an existing project as a library, you can reference
the library project in other Android application projects. For more information, see the
<a href="#ReferencingLibraryProject">Referencing a library project</a> section.
<h3>Creating the manifest file</h3>
<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>
<h2 id="ReferencingLibraryProject">Referencing a library project</h2>
<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>Make sure that both the project library and the application project that depends on it are
in your workspace. If one of the projects is missing, import it into your workspace.</li>
<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>Figure 2 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">
<p class="img-caption"><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>
<h3>Declaring library components in the manifest file</h3>
<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>

64
docs/html/tools/publishing/app-signing-eclipse.jd
View File

@@ -1,64 +0,0 @@
page.title=Signing Your Applications from Eclipse with ADT
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#signing">Signing Your App for Release</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li>
</ol>
</div>
</div>
<p>Android requires that all apps be digitally signed with a certificate before they can be
installed. Android uses this certificate to identify the author of an app, and the certificate
does not need to be signed by a certificate authority.</p>
<p>This document provides detailed instructions about how to sign your apps in release mode with the
ADT plugin for Eclipse. For information about how to obtain a certificate for signing your app, see
<a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.
</p>
<h2 id="signing">Signing Your App for Release</h2>
<p>To sign your app for release with ADT, follow these steps:</p>
<ol>
<li>Select the project in the Package Explorer and select <strong>File</strong> >
<strong>Export</strong>.</li>
<li>On the <em>Export</em> window, select <strong>Export Android Application</strong> and click
<strong>Next</strong>.</li>
<li>On the <em>Export Android Application</em> window, select the project you want to sign and
click <strong>Next</strong>.</li>
<li>
<p>On the next window, enter the location to create a keystore and a keystore password. If you
already have a keystore, select <strong>Use existing keystore</strong>, enter your keystore's
location and password, and go to step 6.</p>
<img src="{@docRoot}images/tools/signadt3.png" alt=""
width="488" height="270" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 6</strong>. Select a keystore in ADT.</p>
</li>
<li><p>On the next window, provide the required information as shown in figure 5.<p>
<p>Your key should be valid for at least 25 years, so you can sign app updates with the same key
through the lifespan of your app.</p>
<img src="{@docRoot}images/tools/signadt4.png" alt=""
width="488" height="448" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 7</strong>. Create a private key in ADT.</p>
</li>
<li><p>On the next window, select the location to export the signed APK.</p>
<img src="{@docRoot}images/tools/signadt5.png" alt=""
width="488" height="217" style="margin-top:15px"/>
<p class="img-caption"><strong>Figure 8</strong>. Export the signed APK in ADT.</p>
</li>
</ol>

535
docs/html/tools/testing/testing_eclipse.jd
View File

@@ -1,535 +0,0 @@
page.title=Testing from Eclipse with ADT
parent.title=Testing
parent.link=index.html
@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 an Android application with the
basic processes for creating and running applications with ADT, as described in
<a href="{@docRoot}tools/projects/projects-eclipse.html">Managing Projects from
Eclipse</a>
and <a href="{@docRoot}tools/building/building-eclipse.html">Building and Running
from Eclipse</a>.
You may also want to read
<a href="{@docRoot}tools/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}tools/testing/testing_otheride.html">Testing from 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}tools/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}tools/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}tools/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 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}tools/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}tools/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}tools/help/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}tools/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}tools/help/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>

47
docs/html/tools/tools_toc.cs
View File

@@ -17,7 +17,7 @@
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot?>tools/studio/index.html">Android Studio</a>
<a href="<?cs var:toroot?>tools/studio/index.html"><span class="en">Android Studio</span></a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>tools/studio/studio-config.html">
@@ -26,6 +26,15 @@
Features</a></li>
<li><a href="<?cs var:toroot ?>sdk/installing/studio-tips.html">
Tips and Tricks</a></li>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>sdk/installing/migrate.html">
<span class="en">
Migrating from Eclipse ADT</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>tools/studio/eclipse-transition-guide.html">
<span class="en">Transition Guide</span></a></li>
</ul>
</li>
</ul>
</li><!-- End of Android Studio menu -->
@@ -39,7 +48,9 @@
</div>
<ul>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>tools/devices/index.html"><span class="en">Setting Up Virtual Devices</span></a></div>
<div class="nav-section-header"><a href="<?cs var:toroot ?>tools/devices/index.html">
<span class="en">
Setting Up Virtual Devices</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>tools/devices/managing-avds.html"><span class="en">With AVD Manager</span></a></li>
<li><a href="<?cs var:toroot ?>tools/devices/managing-avds-cmdline.html"><span class="en">From the Command Line</span></a></li>
@@ -358,38 +369,6 @@ class="en">Data Binding Library</span></a></div>
</ul>
</li> -->
<!-- Eclipse ADT menu-->
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>tools/help/adt.html">
<span class="en">Eclipse with ADT</span></a>
</div>
<ul>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>sdk/installing/migrate.html">
<span class="en">Migrating to Android Studio</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>tools/studio/eclipse-transition-guide.html">
Transition Guide</span></a> </li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>sdk/installing/installing-adt.html">
<span class="en">Installing the Eclipse Plugin</span></a></li>
<li><a href="<?cs var:toroot ?>tools/projects/projects-eclipse.html">Managing Projects</a></li>
<li><a href="<?cs var:toroot ?>tools/building/building-eclipse.html">Building and Running</a></li>
<li><a href="<?cs var:toroot ?>tools/building/building-cmdline-ant.html">Building with Ant</a></li>
<li><a href="<?cs var:toroot ?>tools/testing/testing_eclipse.html">Testing</a></li>
<li><a href="<?cs var:toroot ?>tools/debugging/debugging-projects.html">Debugging</a></li>
<li><a href="<?cs var:toroot ?>tools/publishing/app-signing-eclipse.html">Signing Your Apps</a></li>
</ul>
</li><!-- end of Eclipse -->
</ul><!-- nav -->
<script type="text/javascript">
<!--
buildToggleLists();