diff options
Diffstat (limited to 'docs/html/guide/developing/eclipse-adt.jd')
| -rw-r--r-- | docs/html/guide/developing/eclipse-adt.jd | 860 |
1 files changed, 0 insertions, 860 deletions
diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd deleted file mode 100644 index f8d32e7..0000000 --- a/docs/html/guide/developing/eclipse-adt.jd +++ /dev/null @@ -1,860 +0,0 @@ -page.title=Developing In Eclipse, with ADT -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#CreatingAProject">Creating an Android Project</a></li> - <li><a href="#AVD">Creating an AVD</a></li> - <li><a href="#Running">Running Your Application</a> - <ol> - <li><a href="#RunningOnEmulator">Running on the emulator</a></li> - <li><a href="#RunningOnDevice">Running on a device</a></li> - </ol> - </li> - <li><a href="#RunConfig">Creating a Run Configuration</a></li> - <li><a href="#Signing">Setting Up Application Signing</a></li> - <li><a href="#libraryProject">Working with Library Projects</a> - <ol> - <li><a href="#libraryReqts">Development requirements</a></li> - <li><a href="#librarySetup">Setting up a library project</a></li> - <li><a href="#libraryReference">Referencing a library project</a></li> - <li><a href="#considerations">Development considerations</a></li> - <li><a href="#libraryMigrating">Migrating library projects to ADT 0.9.8</a></li> - </ol> - </li> - <li><a href="#Tips">Eclipse Tips</a></li> - </div> -</div> - - -<p>The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse -integrated development environment. It allows you to create and debug Android applications easier -and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android -applications:</p> - -<ul> - <li>It gives you access to other Android development tools from inside the Eclipse IDE. For -example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage -port-forwarding, set breakpoints, and view thread and process information directly from -Eclipse.</li> - <li>It provides a New Project Wizard, which helps you quickly create and set up all of the -basic files you'll need for a new Android application.</li> - <li>It automates and simplifies the process of building your Android application.</li> - <li>It provides an Android code editor that helps you write valid XML for your Android -manifest and resource files.</li> - <li>It will even export your project into a signed APK, which can be distributed to users.</li> -</ul> - -<p>To begin developing Android applications in the Eclipse IDE with ADT, you first need to -download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the -steps given in <a href="{@docRoot}sdk/eclipse-adt.html#installing">Installing -the ADT Plugin</a>.</p> - -<p>If you are already developing applications using a version of ADT earlier than 0.9, make -sure to upgrade to the latest version before continuing. See the guide to -<a href="{@docRoot}sdk/eclipse-adt.html#updating">Updating Your ADT Plugin</a>.</p> - -<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of -the ADT plugin. While most of the information covered also applies to previous -versions, if you are using an older version, you may want to consult this document from -the set of documentation included in your SDK package (instead of the online version).</p> - - -<h2 id="CreatingAProject">Creating an Android Project</h2> - -<p>The ADT plugin provides a New Project Wizard that you can use to quickly create a new -Android project (or a project from existing code). To create a new project:</p> - -<ol> - <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li> - <li>Select <strong>Android</strong> > <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 — 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"><uses-sdk></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><Android Version></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 — 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> > <strong>Run</strong> (or -<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin -will automatically create a default launch configuration for the project. Eclipse will then perform -the following:</p> - -<ol> - <li>Compile the project (if there have been changes since the last build).</li> - <li>Create a default launch configuration (if one does not already exist for the -project).</li> - <li>Install and start the application on an emulator (or device), based on the Deployment -Target - defined by the run configuration. - <p>By default, Android run configurations use an "automatic target" mode for - selecting a device target. For information on how automatic target mode selects a - deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual - target modes</a> below.</p> - </li> -</ol> - -<p>If debugging, the application will start in the "Waiting For Debugger" mode. Once the -debugger is attached, Eclipse will open the Debug perspective.</p> - -<p>To set or change the launch configuration used for your project, use the launch configuration -manager. -See <a href="#RunConfig">Creating a Run Configuration</a> for information.</p> - -<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD -for each platform and screen type with which your application is compatible. For -instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should -create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a -href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test -your application on each one.</p> - - -<h3 id="RunningOnDevice">Running on a device</h3> - -<p>Before you can run your application on a device, you must perform some basic setup for your -device:</p> - -<ul> - <li>Declare your application as debuggable in your manifest</li> - <li>Enable USB Debugging on your device</li> - <li>Ensure that your development computer can detect your device when connected via USB</li> -</ul> -<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for -Development</a> for more information.</p> - -<p>Once set up and your device is connected via USB, install your application on the device by -selecting <strong>Run</strong> > <strong>Run</strong> (or -<strong>Run</strong> > <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> > - <strong>Open Run Dialog</strong> (or <strong>Open Debug Dialog</strong>) - </li> - <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> - <strong>Run Configurations</strong> (or - <strong>Debug Configurations</strong>) - </li> - </ul> - </li> - <li>Expand the <strong>Android Application</strong> item and create a new - configuration or open an existing one. - <ul> - <li>To create a new configuration: - <ol> - <li>Select <strong>Android Application</strong> and click the <em>New launch -configuration</em> - icon above the list (or, right-click <strong>Android Application</strong> and click - <strong>New</strong>).</li> - <li>Enter a Name for your configuration.</li> - <li>In the Android tab, browse and select the project you'd like to run with the - configuration.</li> - </ol> - <li>To open an existing configuration, select the configuration name from the list - nested below <strong>Android Application</strong>.</li> - </ul> - </li> - <li>Adjust your desired launch configuration settings. - <p>In the Target tab, consider whether you'd like to use Manual or Automatic mode - when selecting an AVD to run your application. - See the following section on <a href="#AutoAndManualTargetModes">Automatic and manual target - modes</a>).</p> - <p>You can specify any emulator options to the Additional Emulator Command - Line Options field. For example, you could add <code>-scale 96dpi</code> to - scale the AVD's screen to an accurate size, based on the dpi of your - computer monitor. For a full list of emulator options, see the <a - href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> -document.</p> - </li> -</ol> - - -<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> - -<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to -select an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> - -<ol> - <li>If there's a device or emulator already running and its AVD configuration - meets the requirements of the application's build target, the application is installed - and run upon it.</li> - <li>If there's more than one device or emulator running, each of which meets the requirements - of the build target, a "device chooser" is shown to let you select which device to use.</li> - <li>If there are no devices or emulators running that meet the requirements of the build target, - ADT looks at the available AVDs. If one meets the requirements of the build target, - the AVD is used to launch a new emulator, upon which the application is installed and run.</li> - <li>If all else fails, the application will not be run and you will see a console error warning - you that there is no existing AVD that meets the build target requirements.</li> -</ol> - -<p>However, if a "preferred AVD" is selected in the run configuration, then the application -will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator -will be launched.</p> - -<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" -is presented every time that your application is run, so that you can select which AVD to use.</p> - - -<h2 id="Signing">Signing your Applications</h2> - -<p>As you begin developing Android applications, understand that all -Android applications must be digitally signed before the system will install -them on an emulator or an actual device. There are two ways to do this: -with a debug key (for immediate testing on an emulator or development device) -or with a private key (for application distribution).</p> - -<p>The ADT plugin helps you get started quickly by signing your .apk files with -a debug key, prior to installing them on an emulator or development device. This means that you can -quickly run your application from Eclipse without having to -generate your own private key. No specific action on your part is needed, -provided ADT has access to Keytool.However, please note that if you intend -to publish your application, you <strong>must</strong> sign the application with your -own private key, rather than the debug key generated by the SDK tools.</p> - -<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your -Applications</a>, which provides a thorough guide to application signing on Android -and what it means to you as an Android application developer. The document also includes -a guide to exporting and signing your application with the ADT's Export Wizard.</p> - - -<h2 id="libraryProject">Working with Library Projects</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Library project example code</h2> - -<p>The SDK includes an example application called TicTacToeMain that shows how a -dependent application can use code and resources from an Android Library -project. The TicTacToeMain application uses code and resources from an example -library project called TicTacToeLib. - -<p style="margin-top:1em;">To download the sample applications and run them as -projects in your environment, use the <em>Android SDK and AVD Manager</em> to -download the "Samples for SDK API 8" component into your SDK. </p> - -<p style="margin-top:1em;">For more information and to browse the code of the -samples, see the <a -href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain -application</a>.</p> -</div> -</div> - -<p>An Android <em>library project</em> is a development project that holds -shared Android source code and resources. Other Android application projects can -reference the library project and, at build time, include its compiled sources -in their <code>.apk</code> files. Multiple application projects can reference -the same library project and any single application project can reference -multiple library projects. </p> - -<p>If you have source code and resources that are common to multiple application -projects, you can move them to a library project so that it is easier to -maintain across applications and versions. Here are some common scenarios in -which you could make use of library projects: </p> - -<ul> -<li>If you are developing multiple related applications that use some of the -same components, you could move the redundant components out of their respective -application projects and create a single, reuseable set of the same components -in a library project. </li> -<li>If you are creating an application that exists in both free and paid -versions, you could move the part of the application that is common to both versions -into a library project. The two dependent projects, with their different package -names, will reference the library project and provide only the difference -between the two application versions.</li> -</ul> - -<p>Structurally, a library project is similar to a standard Android application -project. For example, it includes a manifest file at the project root, as well -as <code>src/</code>, <code>res/</code> and similar directories. The project can -contain the same types of source code and resources as a standard -Android project, stored in the same way. For example, source code in the library -project can access its own resources through its <code>R</code> class. </p> - -<p>However, a library project differs from an standard Android application -project in that you cannot compile it directly to its own <code>.apk</code> or -run it on the Android platform. Similarly, you cannot export the library project -to a self-contained JAR file, as you would do for a true library. Instead, you -must compile the library indirectly, by referencing the library from a dependent -application's build path, then building that application. </p> - -<p>When you build an application that depends on a library project, the SDK -tools compile the library and merge its sources with those in the main project, -then use the result to generate the <code>.apk</code>. In cases where a resource -ID is defined in both the application and the library, the tools ensure that the -resource declared in the application gets priority and that the resource in the -library project is not compiled into the application <code>.apk</code>. This -gives your application the flexibility to either use or redefine any resource -behaviors or values that are defined in any library.</p> - -<p>To organize your code further, your application can add references to -multiple library projects, then specify the relative priority of the resources -in each library. This lets you build up the resources actually used in your -application in a cumulative manner. When two libraries referenced from an -application define the same resource ID, the tools select the resource from the -library with higher priority and discard the other. </p> - -<p>ADT lets you add references to library projects and set their relative -priority from the application project's Properties. As shown in Figure 2, -below, once you've added a reference to a library project, you can use the -<strong>Up</strong> and <strong>Down</strong> controls to change the ordering, -with the library listed at the top getting the higher priority. At build time, -the libraries are merged with the application one at a time, starting from the -lowest priority to the highest. </p> - -<p>Note that a library project cannot itself reference another library project -and that, at build time, library projects are <em>not</em> merged with each -other before being merged with the application. However, note that a library can -import an external library (JAR) in the normal way.</p> - -<p>The sections below describe how to use ADT to set up and manage library your -projects. Once you've set up your library projects and moved code into them, you -can import library classes and resources to your application in the normal way. -</p> - - -<h3 id="libraryReqts">Development requirements</h3> - -<p>Android library projects are a build-time construct, so you can use them to -build a final application <code>.apk</code> that targets any API level and is -compiled against any version of the Android library. </p> - -<p>However, to use library projects, you need to update your development -environment to use the latest tools and platforms, since older releases of the -tools and platforms do not support building with library projects. Specifically, -you need to download and install the versions listed below:</p> - -<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools -and plaforms on which you can develop library projects.</p> - -<table> -<tr> -<th>Component</th> -<th>Minimum Version</th> -</tr> -<tr> -<td>SDK Tools</td> -<td>r6 (or higher)</td> -</tr> -<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> -<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> -<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> -<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> -<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> -</table> - -<p>You can download the tools and platforms using the <em>Android SDK and AVD -Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK -Components</a>. To install or update ADT, use the Eclipse Updater as described -in <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p> - - -<h3 id="librarySetup">Setting up a library project</h3> - -<p>A library project is a standard Android project, so you can create a new one in the -same way as you would a new application project. Specifically, you can use -the New Project Wizard, as described in <a href="#CreatingAProject">Creating an -Android Project</a>, above. </p> - -<p>When you are creating the library project, you can select any application -name, package, and set other fields as needed, as shown in the diagram below. -Click Finish to create the project in the workspace.</p> - -<p>Next, set the project's Properties to indicate that it is a library project:</p> - -<ol> -<li>In the <strong>Package Explorer</strong>, right-click the library project -and select <strong>Properties</strong>.</li> -<li>In the <strong>Properties</strong> window, select the "Android" properties -group at left and locate the <strong>Library</strong> properties at right. </li> -<li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li> -<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li> -</ol> - -<p>The new project is now marked as a library project. You can begin moving -source code and resources into it, as described in the sections below. </p> - -<p>You can also convert an existing application project into a library. To do -so, simply open the Properties for the project and select the "is Library" -checkbox. Other application projects can now reference the existing project as a -library project.</p> - -<img src="{@docRoot}images/developing/adt-props-isLib.png" style="margin:0;padding:0;" /> -<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 1.</strong> -Marking a project as an Android library project. </p> - -<h4>Creating the manifest file</h4> - -<p>A library project's manifest file must declare all of the shared components -that it includes, just as would a standard Android application. For more -information, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - -<p>For example, the <a -href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> -example library project declares the Activity <code>GameActivity</code>: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="GameActivity" /> - ... - </application> -</manifest></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><activity></code>, -<code><service></code>, <code><receiver></code>, -<code><provider></code>, and so on, as well as -<code><permission></code>, <code><uses-library></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><manifest> - ... - <application> - ... - <activity android:name="com.example.android.tictactoe.library.GameActivity" /> - ... - </application> -</manifest></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><uses-library></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 — or lower than — that used by the application. -If the library project uses an API level that is higher than that of the -application, the application project will fail to compile. It is perfectly -acceptable to have a library that uses the Android 1.5 API (API level 3) and -that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) -project, for instance.</p> - -<p><strong>No restriction on library package name</strong></p> - -<p>There is no requirement for the package name of a library to be the same as -that of applications that use it.</p> - -<p><strong>Multiple R classes in gen/ folder of application project</strong></p> - -<p>When you build the dependent application project, the code of any libraries -is compiled and merged to the application project. Each library has its own -<code>R</code> class, named according to the library's package name. The -<code>R</code> class generated from the resources of the main project and of the -library is created in all the packages that are needed including the main -project’s package and the libraries’ packages.</p> - -<p><strong>Testing a library project</strong></p> - -<p>There are two recommended ways of setting up testing on code and resources in -a library project: </p> - -<ul> -<li>You can set up a <a -href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a> -that instruments an application project that depends on the library project. You -can then add tests to the project for library-specific features.</li> -<li>You can set up a set up a standard application project that depends on the -library and put the instrumentation in that project. This lets you create a -self-contained project that contains both the tests/instrumentations and the -code to test.</li> -</ul> - -<p><strong>Library project storage location</strong></p> - -<p>There are no specific requirements on where you should store a library -project, relative to a dependent application project, as long as the application -project can reference the library project by a relative link. You can place the -library project What is important is that the main project can reference the -library project through a relative link.</p> - -<h3 id="libraryMigrating">Migrating library projects to ADT 0.9.8</h3> - -<p>This section provides information about how to migrate a library project -created with ADT 0.9.7 to ADT 0.9.8 (or higher). The migration is needed only if -you are developing in Eclipse with ADT and assumes that you have also upgraded -to SDK Tools r7 (or higher). </p> - -<p>The way that ADT handles library projects has changed between -ADT 0.9.7 and ADT 0.9.8. Specifically, in ADT 0.9.7, the <code>src/</code> -source folder of the library was linked into the dependent application project -as a folder that had the same name as the library project. This worked because -of two restrictions on the library projects:</p> - -<ul> -<li>The library was only able to contain a single source folder (excluding the -special <code>gen/</code> source folder), and</li> -<li>The source folder was required to have the name <code>src/</code> and be -stored at the root of the project.</li> -</ul> - -<p>In ADT 0.9.8, both of those restrictions were removed. A library project can -have as many source folders as needed and each can have any name. Additionally, -a library project can store source folders in any location of the project. For -example, you could store sources in a <code>src/java/</code> directory. In order -to support this, the name of the linked source folders in the main project are -now called <<em>library-name</em>>_<<em>folder-name</em>> 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> — 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> > -<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 "zip", 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> > <strong>Show - View</strong> > <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(".zip")</code></td> - <td><code>(boolean) true</code></td> - </tr> - <tr> - <td><code>zip.endsWith(".jar")</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 "scrapbook".</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> ---> |