guide/developing/eclipse-adt.jd

page.title=Developing In Eclipse, with ADT
@jd:body

<div id="qv-wrapper">
  <div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#CreatingAProject">Creating an Android Project</a></li>
    <li><a href="#AVD">Creating an AVD</a></li>
    <li><a href="#Running">Running Your Application</a>
      <ol>
        <li><a href="#RunningOnEmulator">Running on the emulator</a></li>
        <li><a href="#RunningOnDevice">Running on a device</a></li>
      </ol>
    </li>
    <li><a href="#RunConfig">Creating a Custom Run Configuration</a></li>
    <li><a href="#Signing">Setting Up Application Signing</a></li>
    <li><a href="#libraryProject">Working with Library Projects</a>
      <ol>
        <li><a href="#libraryReqts">Development requirements</a></li>
        <li><a href="#librarySetup">Setting up a library project</a></li>
        <li><a href="#libraryReference">Referencing a library project</a></li>
        <li><a href="#considerations">Development considerations</a></li>
        <li><a href="#libraryMigrating">Migrating library projects to ADT 0.9.8</a></li>
      </ol>
    </li>
    <li><a href="#Tips">Eclipse Tips</a></li>
  </div>
</div>


<p>The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse
integrated development environment. It allows you to create and debug Android applications easier
and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android
applications:</p>

<ul>
  <li>It gives you access to other Android development tools from inside the Eclipse IDE. For
example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage
port-forwarding, set breakpoints, and view thread and process information directly from
Eclipse.</li>
  <li>It provides a New Project Wizard, which helps you quickly create and set up all of the
basic files you'll need for a new Android application.</li>
  <li>It automates and simplifies the process of building your Android application.</li>
  <li>It provides an Android code editor that helps you write valid XML for your Android
manifest and resource files.</li>
  <li>It will even export your project into a signed APK, which can be distributed to users.</li>
</ul>

<p>To begin developing Android applications in the Eclipse IDE with ADT, you first need to
download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the
steps given in <a href="{@docRoot}sdk/eclipse-adt.html#installing">Installing
the ADT Plugin</a>.</p>

<p>If you are already developing applications using a version of ADT earlier than 0.9, make
sure to upgrade to the latest version before continuing. See the guide to
<a href="{@docRoot}sdk/eclipse-adt.html#updating">Updating Your ADT Plugin</a>.</p>

<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of
the ADT plugin. While most of the information covered also applies to previous
versions, if you are using an older version, you may want to consult this document from
the set of documentation included in your SDK package (instead of the online version).</p>


<h2  id="CreatingAProject">Creating an Android Project</h2>

<p>The ADT plugin provides a New Project Wizard that you can use to quickly create a new
Android project (or a project from existing code). To create a new project:</p>

<ol>
  <li>Select <strong>File</strong> &gt; <strong>New</strong> &gt; <strong>Project</strong>.</li>
  <li>Select <strong>Android</strong> &gt; <strong>Android Project</strong>, and click
    <strong>Next</strong>.</li>
  <li>Select the contents for the project:
    <ul>
      <li>Enter a <em>Project Name</em>. This will be the name of the folder where your
        project is created.</li>
      <li>Under Contents, select <strong>Create new project in workspace</strong>.
        Select your project workspace location.</li>
      <li>Under Target, select an Android target to be used as the project's Build Target.
        The Build Target
        specifies which Android platform you'd like your application built against.
        <p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should
        select a target with the lowest platform version possible.</p>
        <p class="note"><strong>Note:</strong> You can change your the Build Target for your
        project at any time: Right-click the project in the Package Explorer, select
        <strong>Properties</strong>, select <strong>Android</strong> and then check
        the desired Project Target.</p>
      </li>
      <li>Under Properties, fill in all necessary fields.
        <ul>
          <li>Enter an <em>Application name</em>. This is the human-readable title for your
            application &mdash; the name that will appear on the Android device.</li>
          <li>Enter a <em>Package name</em>. This is the package namespace (following the same rules
            as for packages in the Java programming language) where all your source code
            will reside.</li>
          <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
            for your main Activity class.</li>
          <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates
            the minimum API Level required to properly run your application.
            Entering this here automatically sets the <code>minSdkVersion</code> attribute in the
            <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a>
            of your Android Manifest file. If you're unsure of the appropriate <a
href="{@docRoot}guide/appendix/api-levels.html">API Level</a> to use,
            copy the API Level listed for the Build Target you selected in the Target tab.</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>Click <strong>Finish</strong>.</li>
</ol>

<p class="note"><strong>Tip:</strong>
You can also start the New Project Wizard from the <em>New</em> icon in the toolbar.</p>

<p>Once you complete the New Project Wizard, ADT creates the following
folders and files in your new project:</p>
  <dl>
    <dt><code>src/</code></dt>
      <dd>Includes your stub Activity Java file. All other Java files for your application
      go here.</dd>
    <dt><code><em>&lt;Android Version&gt;</em>/</code> (e.g., <code>Android 1.1/</code>)</dt>
      <dd>Includes the <code>android.jar</code> file that your application will build against.
      This is determined by the build target that you have chosen in the <em>New Project
      Wizard</em>.</dd>
    <dt><code>gen/</code></dt>
      <dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file
      and interfaces created from AIDL files.</dd>
    <dt><code>assets/</code></dt>
      <dd>This is empty. You can use it to store raw asset files. </dd>
    <dt><code>res/</code></dt>
      <dd>A folder for your application resources, such as drawable files, layout files, string
      values, etc. See
      <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>.</dd>
    <dt><code>AndroidManifest.xml</code></dt>
      <dd>The Android Manifest for your project. See
      <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml
      File</a>.</dd>
    <dt><code>default.properties</code></dt>
      <dd>This file contains project settings, such as the build target. This files is integral
      to the project, as such, it should be maintained in a Source Revision Control system.
      It should never be edited manually &mdash; to edit project properties,
      right-click the project folder and select "Properties".</dd>
  </dl>


<h2 id="AVD">Creating an AVD</h2>

<p>An Android Virtual Device (AVD) is a device configuration for the emulator that
allows you to model real world devices. In order to run an instance of the emulator, you must create
an AVD.</p>

<p>To create an AVD from Eclipse:</p>

<ol>
  <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and
AVD Manager icon in the Eclipse toolbar.</p>
  </li>
  <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click
<strong>New</strong> to create a new AVD.</li>
  <li>Fill in the details for the AVD.
    <p>Give it a name, a platform target, an SD card size, and
    a skin (HVGA is default).</p>
    <p class="note"><strong>Note:</strong> Be sure to define
    a target for your AVD that satisfies your application's Build Target (the AVD
    platform target must have an API Level equal to or greater than the API Level that your
application compiles against).</p>
  </li>
  <li>Click <strong>Create AVD</strong>.</li>
</ol>

<p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or
launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p>

<p>For more information about AVDs, read the
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>
documentation.</p>


<h2 id="Running">Running Your Application</h2>

<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Use the Emulator to Test Different Configurations</h2>
<p>Create multiple AVDs that each define a different device configuration with which your
application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager.
Set the target mode in your app's run configuration to manual, so that when you run your
application, you can select from the available virtual devices.</p>
</div>
</div>

<p>Running your application from Eclipse will usually require just a couple clicks, whether you're
running it on the emulator or on an attached device. The information below describes how to get
set up and run your application from Eclipse.</p>

<h3 id="RunningOnEmulator">Running on the emulator</h3>

<p>Before you can run your application on the Android Emulator,
you <strong>must</strong> <a href="#AVD">create an AVD</a>.</p>

<p>To run (or debug) your application, select <strong>Run</strong> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin
will automatically create a default launch configuration for the project. Eclipse will then perform
the following:</p>

<ol>
  <li>Compile the project (if there have been changes since the last build).</li>
  <li>Create a default launch configuration (if one does not already exist for the
project).</li>
  <li>Install and start the application on an emulator (or device), based on the Deployment
Target
    defined by the run configuration.
    <p>By default, Android run configurations use an "automatic target" mode for
    selecting a device target. For information on how automatic target mode selects a
    deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual
    target modes</a> below.</p>
  </li>
</ol>

<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the
debugger is attached, Eclipse will open the Debug perspective.</p>

<p>To set or change the launch configuration used for your project, use the launch configuration
manager.
See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</p>

<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD
for each platform and screen type with which your application is compatible. For
instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should
create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a
href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test
your application on each one.</p>


<h3 id="RunningOnDevice">Running on a device</h3>

<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>

<ul>
  <li>Declare your application as debuggable in your manifest</li>
  <li>Enable USB Debugging on your device</li>
  <li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
Development</a> for more information.</p>

<p>Once set up and your device is connected via USB, install your application on the device by
selecting <strong>Run</strong> &gt; <strong>Run</strong> (or
<strong>Run</strong> &gt; <strong>Debug</strong>) from the Eclipse menu bar.</p>


<h2 id="RunConfig">Creating a Run Configuration</h2>

<p>The run configuration specifies the project to run, the Activity
to start, the emulator or connected device to use, and so on. When you first run a project
as an <em>Android Application</em>, ADT will automatically create a run configuration.
The default run configuration will
launch the default project Activity and use automatic target mode for device selection
(with no preferred AVD). If the default settings don't suit your project, you can
customize the launch configuration or even create a new.</p>

<p>To create or modify a launch configuration, follow these steps as appropriate
for your Eclipse version:</p>

<ol>
  <li>Open the run configuration manager.
        <ul>
          <li>In Eclipse 3.3 (Europa), select <strong>Run</strong> &gt;
            <strong>Open Run Dialog</strong> (or <strong>Open Debug Dialog</strong>)
          </li>
          <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>&gt;
            <strong>Run Configurations</strong> (or
            <strong>Debug Configurations</strong>)
          </li>
      </ul>
  </li>
  <li>Expand the <strong>Android Application</strong> item and create a new
  configuration or open an existing one.
    <ul>
      <li>To create a new configuration:
        <ol>
          <li>Select <strong>Android Application</strong> and click the <em>New launch
configuration</em>
          icon above the list (or, right-click  <strong>Android Application</strong> and click
          <strong>New</strong>).</li>
          <li>Enter a Name for your configuration.</li>
          <li>In the Android tab, browse and select the project you'd like to run with the
          configuration.</li>
        </ol>
      <li>To open an existing configuration, select the configuration name from the list
      nested below <strong>Android Application</strong>.</li>
    </ul>
  </li>
  <li>Adjust your desired launch configuration settings.
    <p>In the Target tab, consider whether you'd like to use Manual or Automatic mode
    when selecting an AVD to run your application.
    See the following section on <a href=#AutoAndManualModes">Automatic and manual target
    modes</a>).</p>
    <p>You can specify any emulator options to the Additional Emulator Command
    Line Options field. For example, you could add <code>-scale 96dpi</code> to
    scale the AVD's screen to an accurate size, based on the dpi of your
    computer monitor. For a full list of emulator options, see the <a
    href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>
document.</p>
  </li>
</ol>


<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3>

<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
select an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p>

<ol>
  <li>If there's a device or emulator already running and its AVD configuration
  meets the requirements of the application's build target, the application is installed
  and run upon it.</li>
  <li>If there's more than one device or emulator running, each of which meets the requirements
  of the build target, a "device chooser" is shown to let you select which device to use.</li>
  <li>If there are no devices or emulators running that meet the requirements of the build target,
  ADT looks at the available AVDs. If one meets the requirements of the build target,
  the AVD is used to launch a new emulator, upon which the application is installed and run.</li>
  <li>If all else fails, the application will not be run and you will see a console error warning
  you that there is no existing AVD that meets the build target requirements.</li>
</ol>

<p>However, if a "preferred AVD" is selected in the run configuration, then the application
will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator
will be launched.</p>

<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser"
is presented every time that your application is run, so that you can select which AVD to use.</p>


<h2 id="Signing">Signing your Applications</h2>

<p>As you begin developing Android applications, understand that all
Android applications must be digitally signed before the system will install
them on an emulator or an actual device. There are two ways to do this:
with a debug key (for immediate testing on an emulator or development device)
or with a private key (for application distribution).</p>

<p>The ADT plugin helps you get started quickly by signing your .apk files with
a debug key, prior to installing them on an emulator or development device. This means that you can
quickly run your application from Eclipse without having to
generate your own private key. No specific action on your part is needed,
provided ADT has access to Keytool.However, please note that if you intend
to publish your application, you <strong>must</strong> sign the application with your
own private key, rather than the debug key generated by the SDK tools.</p>

<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
Applications</a>, which provides a thorough guide to application signing on Android
and what it means to you as an Android application developer. The document also includes
a guide to exporting and signing your application with the ADT's Export Wizard.</p>


<h2 id="libraryProject">Working with Library Projects</h2>

<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Library project example code</h2>

<p>The SDK includes an example application called TicTacToeMain that shows how a
dependent application can use code and resources from an Android Library
project. The TicTacToeMain application uses code and resources from an example
library project called TicTacToeLib.

<p style="margin-top:1em;">To download the sample applications and run them as
projects in your environment, use the <em>Android SDK and AVD Manager</em> to
download the "Samples for SDK API 8" component into your SDK. </p>

<p style="margin-top:1em;">For more information and to browse the code of the
samples, see the <a
href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain
application</a>.</p>
</div>
</div>

<p>An Android <em>library project</em> is a development project that holds
shared Android source code and resources. Other Android application projects can
reference the library project and, at build time, include its compiled sources
in their <code>.apk</code> files. Multiple application projects can reference
the same library project and any single application project can reference
multiple library projects. </p>

<p>If you have source code and resources that are common to multiple application
projects, you can move them to a library project so that it is easier to
maintain across applications and versions. Here are some common scenarios in
which you could make use of library projects: </p>

<ul>
<li>If you are developing multiple related applications that use some of the
same components, you could move the redundant components out of their respective
application projects and create a single, reuseable set of the same components
in a library project. </li>
<li>If you are creating an application that exists in both free and paid
versions, you could move the part of the application that is common to both versions
into a library project. The two dependent projects, with their different package
names, will reference the library project and provide only the difference
between the two application versions.</li>
</ul>

<p>Structurally, a library project is similar to a standard Android application
project. For example, it includes a manifest file at the project root, as well
as <code>src/</code>, <code>res/</code> and similar directories. The project can
contain the same types of source code and resources as a standard
Android project, stored in the same way. For example, source code in the library
project can access its own resources through its <code>R</code> class. </p>

<p>However, a library project differs from an standard Android application
project in that you cannot compile it directly to its own <code>.apk</code> or
run it on the Android platform. Similarly, you cannot export the library project
to a self-contained JAR file, as you would do for a true library. Instead, you
must compile the library indirectly, by referencing the library from a dependent
application's build path, then building that application. </p>

<p>When you build an application that depends on a library project, the SDK
tools compile the library and merge its sources with those in the main project,
then use the result to generate the <code>.apk</code>. In cases where a resource
ID is defined in both the application and the library, the tools ensure that the
resource declared in the application gets priority and that the resource in the
library project is not compiled into the application <code>.apk</code>. This
gives your application the flexibility to either use or redefine any resource
behaviors or values that are defined in any library.</p>

<p>To organize your code further, your application can add references to
multiple library projects, then specify the relative priority of the resources
in each library. This lets you build up the resources actually used in your
application in a cumulative manner. When two libraries referenced from an
application define the same resource ID, the tools select the resource from the
library with higher priority and discard the other. </p>

<p>ADT lets you add references to library projects and set their relative
priority from the application project's Properties. As shown in Figure 2,
below, once you've added a reference to a library project, you can use the
<strong>Up</strong> and <strong>Down</strong> controls to change the ordering,
with the library listed at the top getting the higher priority. At build time,
the libraries are merged with the application one at a time, starting from the
lowest priority to the highest. </p>

<p>Note that a library project cannot itself reference another library project
and that, at build time, library projects are <em>not</em> merged with each
other before being merged with the application. However, note that a library can
import an external library (JAR) in the normal way.</p>

<p>The sections below describe how to use ADT to set up and manage library your
projects. Once you've set up your library projects and moved code into them, you
can import library classes and resources to your application in the normal way.
</p>


<h3 id="libraryReqts">Development requirements</h3>

<p>Android library projects are a build-time construct, so you can use them to
build a final application <code>.apk</code> that targets any API level and is
compiled against any version of the Android library. </p>

<p>However, to use library projects, you need to update your development
environment to use the latest tools and platforms, since older releases of the
tools and platforms do not support building with library projects. Specifically,
you need to download and install the versions listed below:</p>

<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools
and plaforms on which you can develop library projects.</p>

<table>
<tr>
<th>Component</th>
<th>Minimum Version</th>
</tr>
<tr>
<td>SDK Tools</td>
<td>r6 (or higher)</td>
</tr>
<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr>
<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr>
<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr>
<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr>
<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr>
<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr>
</table>

<p>You can download the tools and platforms using the <em>Android SDK and AVD
Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK
Components</a>. To install or update ADT, use the Eclipse Updater as described
in <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p>


<h3 id="librarySetup">Setting up a library project</h3>

<p>A library project is a standard Android project, so you can create a new one in the
same way as you would a new application project. Specifically, you can use
the New Project Wizard, as described in <a href="#CreatingAProject">Creating an
Android Project</a>, above. </p>

<p>When you are creating the library project, you can select any application
name, package, and set other fields as needed, as shown in the diagram below.
Click Finish to create the project in the workspace.</p>

<p>Next, set the project's Properties to indicate that it is a library project:</p>

<ol>
<li>In the <strong>Package Explorer</strong>, right-click the library project
and select <strong>Properties</strong>.</li>
<li>In the <strong>Properties</strong> window, select the "Android" properties
group at left and locate the <strong>Library</strong> properties at right. </li>
<li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li>
<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>

<p>The new project is now marked as a library project. You can begin moving
source code and resources into it, as described in the sections below. </p>

<p>You can also convert an existing application project into a library. To do
so, simply open the Properties for the project and select the "is Library"
checkbox. Other application projects can now reference the existing project as a
library project.</p>

<img src="{@docRoot}images/developing/adt-props-isLib.png" style="margin:0;padding:0;" />
<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 1.</strong>
Marking a project as an Android library project. </p>

<h4>Creating the manifest file</h4>

<p>A library project's manifest file must declare all of the shared components
that it includes, just as would a standard Android application. For more
information, see the documentation for <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>

<p>For example, the <a
href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a>
example library project declares the Activity <code>GameActivity</code>: </p>

<pre>&lt;manifest&gt;
  ...
  &lt;application&gt;
    ...
    &lt;activity android:name="GameActivity" /&gt;
    ...
  &lt;/application&gt;
  ...
&lt;/manifest&gt;</pre>


<h3 id="libraryReference">Referencing a library project from an application</h3>

<p>If you are developing an application and want to include the shared code or
resources from a library project, you can do so easily by adding a reference to
the library project in the application project's Properties.</p>

<p>To add a reference to a library project, follow these steps: </p>

<ol>
<li>In the <strong>Package Explorer</strong>, right-click the dependent project
and select <strong>Properties</strong>.</li>
<li>In the <strong>Properties</strong> window, select the "Android" properties group
at left and locate the <strong>Library</strong> properties at right.</li>
<li>Click <strong>Add</strong> to open the <strong>Project Selection</strong>
dialog. </li>
<li>From the list of available library projects, select a project and click
<strong>OK</strong>.</li>
<li>When the dialog closes, click <strong>Apply</strong> in the
<strong>Properties</strong> window.</li>
<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>

<p>As soon as the Properties dialog closes, Eclipse rebuilds the project,
including the contents of the library project. </p>

<p>The figure below shows the Properties dialog that lets you add library
references and move them up and down in priority. </p>

<img src="{@docRoot}images/developing/adt-props-libRef.png" style="margin:0;padding:0;" />
<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 2.</strong>
Adding a reference to a library project in the properties of an application project. </p>

<p>If you are adding references to multiple libraries, note that you can set
their relative priority (and merge order) by selecting a library and using the
<strong>Up</strong> and <strong>Down</strong> controls. The tools merge the
referenced libraries with your application starting from lowest priority (bottom
of the list) to highest (top of the list). If more than one library defines the
same resource ID, the tools select the resource from the library with higher
priority. The application itself has highest priority and its resources are
always used in preference to identical resource IDs defined in libraries.</p>

<h4>Declaring library components in the the manifest file</h4>

<p>In the manifest file of the application project, you must add declarations
of all components that the application will use that are imported from a library
project. For example, you must declare any <code>&lt;activity&gt;</code>,
<code>&lt;service&gt;</code>, <code>&lt;receiver&gt;</code>,
<code>&lt;provider&gt;</code>, and so on, as well as
<code>&lt;permission&gt;</code>, <code>&lt;uses-library&gt;</code>, and similar
elements.</p>

<p>Declarations should reference the library components by their fully-qualified
package names, where appropriate. </p>

<p>For example, the <a
href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a>
example application declares the library Activity <code>GameActivity</code>
like this: </p>

<pre>&lt;manifest&gt;
  ...
  &lt;application&gt;
    ...
    &lt;activity android:name="com.example.android.tictactoe.library.GameActivity" /&gt;
    ...
  &lt;/application&gt;
  ...
&lt;/manifest&gt;</pre>

<p>For more information about the manifest file, see the documentation for <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>


<h3 id="considerations">Development considerations</h3>

<p>As you develop your library project and dependent applications, keep the
points listed below in mind.</p>

<p><strong>Resource conflicts</strong></p>

<p>Since the tools merge the resources of a library project with those of a
dependent application project, a given resource ID might be defined in both
projects. In this case, the tools select the resource from the application, or
the library with highest priority, and discard the other resource. As you
develop your applications, be aware that common resource IDs are likely to be
defined in more than one project and will be merged, with the resource from the
application or highest-priority library taking precedence.</p>

<p><strong>Using prefixes to avoid resource conflicts</strong></p>

<p>To avoid resource conflicts for common resource IDs, consider using a prefix
or other consistent naming scheme that is unique to the project (or is  unique
across all projects). </p>

<p><strong>No export of library project to JAR</strong></p>

<p>A library cannot be distributed as a binary file (such as a jar file). This
is because the library project is compiled by the main project to use the
correct resource IDs.</p>

<p><strong>A library project can include a JAR library</strong></p>

<p>You can develop a library project that itself includes a JAR library, however
you need to manually edit the dependent application project's build path and add
a path to the JAR file. </p>

<p><strong>A library project can depend on an external JAR library</strong></p>

<p>You can develop a library project that depends on an external library (for
example, the Maps external library). In this case, the dependent application
must build against a target that includes the external library (for example, the
Google APIs Add-On). Note also that both the library project and the dependent
application must declare the external library their manifest files, in a <a
href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code>&lt;uses-library&gt;</code></a>
element. </p>

<p><strong>Library project can not include raw assets</strong></p>

<p>The tools do not support the use of raw asset files in a library project.
Any asset resources used by an application must be stored in the
<code>assets/</code> directory of the application project
itself.</p>

<p><strong>Targeting different Android platform versions in library project and
application project</strong></p>

<p>A library is compiled as part of the dependent application project, so the
API used in the library project must be compatible with the version of the
Android library used to compile the application project. In general, the library
project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a>
that is the same as &mdash; or lower than &mdash; that used by the application.
If the library project uses an API level that is higher than that of the
application, the application project will fail to compile. It is perfectly
acceptable to have a library that uses the Android 1.5 API (API level 3) and
that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7)
project, for instance.</p>

<p><strong>No restriction on library package name</strong></p>

<p>There is no requirement for the package name of a library to be the same as
that of applications that use it.</p>

<p><strong>Multiple R classes in gen/ folder of application project</strong></p>

<p>When you build the dependent application project, the code of any libraries
is compiled and merged to the application project. Each library has its own
<code>R</code> class, named according to the library's package name. The
<code>R</code> class generated from the resources of the main project and of the
library is created in all the packages that are needed including the main
projects package and the libraries packages.</p>

<p><strong>Testing a library project</strong></p>

<p>There are two recommended ways of setting up testing on code and resources in
a library project: </p>

<ul>
<li>You can set up a <a
href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a>
that instruments an application project that depends on the library project. You
can then add tests to the project for library-specific features.</li>
<li>You can set up a set up a standard application project that depends on the
library and put the instrumentation in that project. This lets you create a
self-contained project that contains both the tests/instrumentations and the
code to test.</li>
</ul>

<p><strong>Library project storage location</strong></p>

<p>There are no specific requirements on where you should store a library
project, relative to a dependent application project, as long as the application
project can reference the library project by a relative link. You can place the
library project What is important is that the main project can reference the
library project through a relative link.</p>

<h3 id="libraryMigrating">Migrating library projects to ADT 0.9.8</h3>

<p>This section provides information about how to migrate a library project
created with ADT 0.9.7 to ADT 0.9.8 (or higher). The migration is needed only if
you are developing in Eclipse with ADT and assumes that you have also upgraded
to SDK Tools r7 (or higher). </p>

<p>The way that ADT handles library projects has changed between
ADT 0.9.7 and ADT 0.9.8. Specifically, in ADT 0.9.7, the <code>src/</code>
source folder of the library was linked into the dependent application project
as a folder that had the same name as the library project. This worked because
of two restrictions on the library projects:</p>

<ul>
<li>The library was only able to contain a single source folder (excluding the
special <code>gen/</code> source folder), and</li>
<li>The source folder was required to have the name <code>src/</code> and be
stored at the root of the project.</li>
</ul>

<p>In ADT 0.9.8, both of those restrictions were removed. A library project can
have as many source folders as needed and each can have any name. Additionally,
a library project can store source folders in any location of the project. For
example, you could store sources in a <code>src/java/</code> directory. In order
to support this, the name of the linked source folders in the main project are
now called &lt;<em>library-name</em>&gt;_&lt;<em>folder-name</em>&gt; For
example: <code>MyLibrary_src/</code> or <code>MyLibrary_src_java/</code>.</p>

<p>Additionally, the linking process now flags those folders in order for ADT to
recognize that it created them. This will allow ADT to automatically migrate the
project to new versions of ADT, should they contain changes to the handling of
library projects. ADT 0.9.7 did not flag the linked source folders, so ADT 0.9.8
cannot be sure whether the old linked folders can be removed safely. After
upgrading ADT to 0.9.8, you will need to remove the old linked folders manually
in a simple two-step process, as described below.</p>

<p>Before you begin, make sure to create a backup copy of your application or
save the latest version to your code version control system. This ensures that
you will be able to easily revert the migration changes in case there is a
problem in your environment.</p>

<p>When you first upgrade to ADT 0.9.8, your main project will look as shown
below, with two linked folders (in this example, <code>MyLibrary</code> and
<code>MyLibrary_src</code> &mdash; both of which link to
<code>MyLibrary/src</code>. Eclipse shows an error on one of them because they
are duplicate links to a single class.</p>

<img src="{@docRoot}images/developing/lib-migration-0.png" alt="">

<p>To fix the error, remove the linked folder that <em>does not</em> contain the
<code>_src</code> suffix. </p>

<ol>
<li>Right click the folder that you want to remove (in this case, the
<code>MyLibrary</code> folder) and choose <strong>Build Path</strong> &gt;
<strong>Remove from Build Path</strong>, as shown below.</li>

<img src="{@docRoot}images/developing/lib-migration-1.png" style="height:600px"
alt="">

<li>Next, When asked about unlinking the folder from the project, select
<strong>Yes</strong>, as shown below.</li>

<img src="{@docRoot}images/developing/lib-migration-2.png" alt="">
</ol>

<p>This should resolve the error and migrate your library project to the new
ADT environment. </p>

<h2 id="Tips">Eclipse Tips</h2>

<h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3>

<p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example,
    when in a function with a String argument called &quot;zip&quot;, you can get
    information about packages and call class methods. You can also invoke arbitrary
    static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will
    start dmTrace. </p>
<p>Open a code execution window, select <strong>Window</strong> &gt; <strong>Show
        View</strong> &gt; <strong>Display</strong> from the main menu to open the
        Display window, a simple text editor. Type your expression, highlight the
        text, and click the 'J' icon (or CTRL + SHIFT + D) to run your
        code. The code runs in the context of the selected thread, which must be
        stopped at a breakpoint or single-step point. (If you suspend the thread
        manually, you have to single-step once; this doesn't work if the thread is
        in Object.wait().)</p>
<p>If you are currently paused on a breakpoint, you can simply highlight and execute
    a piece of source code by pressing CTRL + SHIFT + D. </p>
<p>You can highlight a block of text within the same scope by pressing ALT +SHIFT
    + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select
    smaller blocks. </p>
<p>Here are a few sample inputs and responses in Eclipse using the Display window.</p>

<table width="100%" border="1">
    <tr>
        <th scope="col">Input</th>
        <th scope="col">Response</th>
    </tr>
    <tr>
        <td><code>zip</code></td>
        <td><code>(java.lang.String)
        /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td>
    </tr>
    <tr>
        <td><code>zip.endsWith(&quot;.zip&quot;)</code></td>
        <td><code>(boolean) true</code></td>
    </tr>
    <tr>
        <td><code>zip.endsWith(&quot;.jar&quot;)</code></td>
        <td><code>(boolean) false</code></td>
    </tr>
</table>
<p>You can also execute arbitrary code when not debugging by using a scrapbook page.
    Search the Eclipse documentation for &quot;scrapbook&quot;.</p>


<h3>Running DDMS Manually</h3>

<p>Although the recommended way to debug is to use the ADT plugin, you can manually run
DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you
have first started <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a>). </p>


<!-- TODO: clean this up and expand it to cover more wizards and features
<h3>ADT Wizards</h3>

<p>Notice that the "New Android Project" wizard has been expanded to use the multi-platform
capabilities of the new SDK.</p>

<p>There is now a "New XML File" wizard that lets you create skeleton XML resource
files for your Android projects. This makes it easier to create a new layout, a new menu, a
new strings file, etc.</p>

<p>Both wizards are available via <strong>File > New</strong> and new icons in the main
Eclipse toolbar (located to the left of the Debug and Run icons).
If you do not see the new icons, you may need to select <strong>Window > Reset
Perspective</strong> from the Java perspective.</p>
-->