diff options
Diffstat (limited to 'docs/html/guide/developing/other-ide.jd')
| -rw-r--r-- | docs/html/guide/developing/other-ide.jd | 937 |
1 files changed, 0 insertions, 937 deletions
diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd deleted file mode 100644 index d309f47..0000000 --- a/docs/html/guide/developing/other-ide.jd +++ /dev/null @@ -1,937 +0,0 @@ -page.title=Developing In Other IDEs -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#CreatingAProject">Creating an Android Project</a></li> - <li><a href="#Signing">Preparing to Sign Your Application</a></li> - <li><a href="#Building">Building Your Application</a> - <ol> - <li><a href="#DebugMode">Building in debug mode</a></li> - <li><a href="#ReleaseMode">Building in release mode</a></li> - </ol> - </li> - <li><a href="#AVD">Creating an AVD</a></li> - <li><a href="#Running">Running Your Application</a> - <ol> - <li><a href="#RunningOnEmulator">Running on the emulator</a></li> - <li><a href="#RunningOnDevice">Running on a device</a></li> - </ol> - </li> - <li><a href="#libraryProject">Working with Library Projects</a> - <ol> - <li><a href="#libraryReqts">Development requirements</a></li> - <li><a href="#librarySetup">Setting up a library project</a></li> - <li><a href="#libraryReference">Referencing a library project</a></li> - <li><a href="#depAppBuild">Building a dependent application project</a></li> - <li><a href="#considerations">Development considerations</a></li> - </ol> - </li> - <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> - <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> - <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></li> - </ol> -</div> -</div> - -<p>The recommended way to develop an Android application is to use -<a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the ADT plugin</a>. -The ADT plugin provides editing, building, debugging, and .apk packaging and signing functionality -integrated right into the IDE.</p> - -<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, -or in a basic editor, such as Emacs, you can do that instead. The SDK -includes all the tools you need to set up an Android project, build it, debug it and then -package it for distribution. This document is your guide to using these tools.</p> - - -<h2 id="EssentialTools">Essential Tools</h2> - -<p>When developing in IDEs or editors other than Eclipse, you'll require -familiarity with the following Android SDK tools:</p> - -<dl> - <dt><a href="{@docRoot}guide/developing/tools/othertools.html#android">android</a></dt> - <dd>To create/update Android projects and to create/move/delete AVDs.</dd> - <dt><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></dt> - <dd>To run your Android applications on an emulated Android platform.</dd> - <dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt> - <dd>To interface with your emulator or connected device (install apps, - shell the device, issue commands, etc.). - </dd> -</dl> - -<p>In addition to the above tools, included with the SDK, you'll use the following -open source and third-party tools:</p> - -<dl> - <dt>Ant</dt> - <dd>To compile and build your Android project into an installable .apk file.</dd> - <dt>Keytool</dt> - <dd>To generate a keystore and private key, used to sign your .apk file.</dd> - <dt>Jarsigner (or similar signing tool)</dt> - <dd>To sign your .apk file with a private key generated by keytool.</dd> -</dl> - -<p>In the topics that follow, you'll be introduced to each of these tools as necessary. -For more advanced operations, please read the respective documentation for each tool.</p> - - -<h2 id="CreatingAProject">Creating an Android Project</h2> - -<p>To create an Android project, you must use the <code>android</code> tool. When you create -a new project with <code>android</code>, it will generate a project directory -with some default application files, stub files, configuration files and a build file.</p> - - -<h3 id="CreatingANewProject">Creating a new Project</h3> - -<p>If you're starting a new project, use the <code>android create project</code> -command to generate all the necessary files and folders.</p> - -<p>To create a new Android project, open a command-line, -navigate to the <code>tools/</code> directory of your SDK and run:</p> -<pre> -android create project \ ---target <em><target_ID></em> \ ---name <em><your_project_name></em> \ ---path <em>path/to/your/project</em> \ ---activity <em><your_activity_name></em> \ ---package <em><your_package_namespace></em> -</pre> - -<ul> - <li><code>target</code> is the "build target" for your application. It corresponds - to an Android platform library (including any add-ons, such as Google APIs) that you would like to - build your project against. To see a list of available targets and their corresponding IDs, - execute: <code>android list targets</code>.</li> - <li><code>name</code> is the name for your project. This is optional. If provided, this name will -be used - for your .apk filename when you build your application.</li> - <li><code>path</code> is the location of your project directory. If the directory does not exist, - it will be created for you.</li> - <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This -class file - will be created for you inside - -<code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code> -. - This will also be used for your .apk filename unless you provide a the <code>name</code>.</li> - <li><code>package</code> is the package namespace for your project, following the same rules as -for - packages in the Java programming language.</li> -</ul> - -<p>Here's an example:</p> -<pre> -android create project \ ---target 1 \ ---name MyAndroidApp \ ---path ./MyAndroidAppProject \ ---activity MyAndroidAppActivity \ ---package com.example.myandroid -</pre> - -<p>The tool generates the following files and directories:</p> - -<ul> - <li><code>AndroidManifest.xml</code> - The application manifest file, - synced to the specified Activity class for the project.</li> - <li><code>build.xml</code> - Build file for Ant.</li> - <li><code>default.properties</code> - Properties for the build system. <em>Do not modify - this file</em>.</li> - <li><code>build.properties</code> - Customizable properties for the build system. You can edit -this - file to override default build settings used by Ant and provide a pointer to your keystore and key -alias - so that the build tools can sign your application when built in release mode.</li> - <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class - you specified during project creation.</li> - <li><code>bin/</code> - Output directory for the build script.</li> - <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>. -</li> - <li><code>libs/</code> - Holds private libraries.</li> - <li><code>res/</code> - Holds project resources.</li> - <li><code>src/</code> - Holds source code.</li> - <li><code>tests/</code> - Holds a duplicate of all-of-the-above, for testing purposes.</li> -</ul> - -<p>Once you've created your project, you're ready to begin development. -You can move your project folder wherever you want for development, but keep in mind -that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> -(adb) — located in the SDK <code>platform-tools/</code> directory — to send your -application -to the emulator (discussed later). So you need access between your project solution and -the <code>platform-tools/</code> folder.</p> - -<p class="caution"><strong>Caution:</strong> You should refrain from moving the -location of the SDK directory, because this will break the build scripts. (They -will need to be manually updated to reflect the new SDK location before they will -work again.)</p> - - -<h3 id="UpdatingAProject">Updating a project</h3> - -<p>If you're upgrading a project from an older version of the Android SDK or want to create -a new project from existing code, use the -<code>android update project</code> command to update the project to the new development -environment. You can also use this command to revise the build target of an existing project -(with the <code>--target</code> option) and the project name (with the <code>--name</code> -option). The <code>android</code> tool will generate any files and -folders (listed in the previous section) that are either missing or need to be updated, -as needed for the Android project.</p> - -<p>To update an existing Android project, open a command-line -and navigate to the <code>tools/</code> directory of your SDK. Now run:</p> -<pre> -android update project --name <em><project_name></em> --target <em><target_ID></em> ---path <em><path_to_your_project></em> -</pre> - -<ul> - <li><code>target</code> is the "build target" for your application. It corresponds to - an Android platform library (including any add-ons, such as Google APIs) that you would - like to build your project against. To see a list of available targets and their corresponding -IDs, - execute: <code>android list targets</code>.</li> - <li><code>path</code> is the location of your project directory.</li> - <li><code>name</code> is the name for the project. This is optional—if you're not - changing the project name, you don't need this.</li> -</ul> - -<p>Here's an example:</p> -<pre> -android update project --name MyApp --target 2 --path ./MyAppProject -</pre> - - -<h2 id="Signing">Preparing to Sign Your Application</h2> - -<p>As you begin developing Android applications, understand that all -Android applications must be digitally signed before the system will install -them on an emulator or device. There are two ways to do this: -with a <em>debug key</em> (for immediate testing on an emulator or development device) -or with a <em>private key</em> (for application distribution).</p> - -<p>The Android build tools help you get started by automatically signing your .apk -files with a debug key at build time. This means -that you can compile your application and install it on the emulator without -having to generate your own private key. However, please note that if you intend -to publish your application, you <strong>must</strong> sign the application with your -own private key, rather than the debug key generated by the SDK tools. </p> - -<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your -Applications</a>, which provides a thorough guide to application signing on Android -and what it means to you as an Android application developer.</p> - - - -<h2 id="Building">Building Your Application</h2> - -<p>There are two ways to build your application: one for testing/debugging your application -— <em>debug mode</em> — and one for building your final package for release — -<em>release mode</em>. As described in the previous -section, your application must be signed before it can be installed on an emulator -or device.</p> - -<p>Whether you're building in debug mode or release mode, you -need to use the Ant tool to compile and build your project. This will create the .apk file -that is installed onto the emulator or device. When you build in debug mode, the .apk -file is automatically signed by the SDK tools with a debug key, so it's instantly ready for -installation -(but only onto an emulator or attached development device). -When you build in release mode, the .apk file is <em>unsigned</em>, so you must manually -sign it with your own private key, using Keytool and Jarsigner.</p> - -<p>It's important that you read and understand -<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly -once you're ready to release your application and share it with end-users. That document describes -the procedure for generating a private key and then using it to sign your .apk file. -If you're just getting started, however, -you can quickly run your applications on an emulator or your own development device by building in -debug mode.</p> - -<p>If you don't have Ant, you can obtain it from the -<a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make -sure it is in your executable PATH. Before calling Ant, you need to declare the JAVA_HOME -environment variable to specify the path to where the JDK is installed.</p> - -<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install -in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of -the space. To fix the problem, you can specify the JAVA_HOME variable like this: -<code>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></code>. The easiest solution, however, is to -install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p> - - -<h3 id="DebugMode">Building in debug mode</h3> - -<p>For immediate application testing and debugging, you can build your application -in debug mode and immediately install it on an emulator. In debug mode, the build tools -automatically sign your application with a debug key and optimize the package with -{@code zipalign}. However, you can (and should) also test your -application in release mode. Debug mode simply allows you to run your application without -manually signing the application.</p> - -<p>To build in debug mode:</p> - -<ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in debug mode: - <pre>ant debug</pre> - <p>This creates your debug .apk file inside the project <code>bin/</code> - directory, named <code><em><your_project_name></em>-debug.apk</code>. The file - is already signed with the debug key and has been aligned with {@code zipalign}.</p> - </li> -</ol> - -<p>Each time you change a source file or resource, you must run Ant -again in order to package up the latest version of the application.</p> - -<p>To install and run your application on an emulator, see the following section -about <a href="#Running">Running Your Application</a>.</p> - - -<h3 id="ReleaseMode">Building in release mode</h3> - -<p>When you're ready to release and distribute your application to end-users, you must build -your application in release mode. Once you have built in release mode, it's a good idea to perform -additional testing and debugging with the final .apk.</p> - -<p>Before you start building your application in release mode, be aware that you must sign -the resulting application package with your private key, and should then align it using the -{@code zipalign} tool. There are two approaches to building in release mode: -build an unsigned package in release mode and then manually sign and align -the package, or allow the build script -to sign and align the package for you.</p> - -<h4 id="ManualReleaseMode">Build unsigned</h4> - -<p>If you build your application <em>unsigned</em>, then you will need to -manually sign and align the package.</p> - -<p>To build an <em>unsigned</em> .apk in release mode:</p> - -<ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in release mode: - <pre>ant release</pre> - </li> -</ol> - -<p>This creates your Android application .apk file inside the project <code>bin/</code> -directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p> - -<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point -and can't be installed until signed with your private key.</p> - -<p>Once you have created the unsigned .apk, your next step is to sign the .apk -with your private key and then align it with {@code zipalign}. To complete this procedure, -read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> - -<p>When your .apk has been signed and aligned, it's ready to be distributed to end-users.</p> - -<h4 id="AutoReleaseMode">Build signed and aligned</h4> - -<p>If you would like, you can configure the Android build script to automatically -sign and align your application package. To do so, you must provide the path to your keystore -and the name of your key alias in your project's {@code build.properties} file. With this -information provided, the build script will prompt you for your keystore and alias password -when you build in release mode and produce your final application package, which will be ready -for distribution.</p> - -<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that -you enter during the build process <strong>will be visible</strong>. If you are -concerned about your keystore and alias password being visible on screen, then you -may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To -instead -perform the signing procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then -continue -with <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> - -<p>To specify your keystore and alias, open the project {@code build.properties} file (found in the -root of the project directory) and add entries for {@code key.store} and {@code key.alias}. -For example:</p> - -<pre> -key.store=path/to/my.keystore -key.alias=mykeystore -</pre> - -<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p> - -<ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in release mode: - <pre>ant release</pre> - </li> - <li>When prompted, enter you keystore and alias passwords. - <p class="caution"><strong>Caution:</strong> As described above, - your password will be visible on the screen.</p> - </li> -</ol> - -<p>This creates your Android application .apk file inside the project <code>bin/</code> -directory, named <code><em><your_project_name></em>-release.apk</code>. -This .apk file has been signed with the private key specified in -{@code build.properties} and aligned with {@code zipalign}. It's ready for -installation and distribution.</p> - - -<h4>Once built and signed in release mode</h4> - -<p>Once you have signed your application with a private key, you can install it on an -emulator or device as discussed in the following section about -<a href="#Running">Running Your Application</a>. -You can also try installing it onto a device from a web server. -Simply upload the signed APK to a web site, then load the .apk URL in your Android web browser to -download the application and begin installation. -(On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p> - - -<h2 id="AVD">Creating an AVD</h2> - -<p>An Android Virtual Device (AVD) is a device configuration for the emulator that -allows you to model real world devices. In order to run an instance of the emulator, you must create -an AVD.</p> - -<p>To create an AVD using the SDK tools:</p> - -<ol> - <li>Navigate to your SDK's <code>tools/</code> directory and execute the {@code android} -tool with no arguments: - <pre>android</pre> - <p>This will launch the SDK and AVD Manager GUI.</p> - </li> - <li>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click -<strong>New</strong> - to create a new AVD.</li> - <li>Fill in the details for the AVD. - <p>Give it a name, a platform target, an SD card size, and - a skin (HVGA is default).</p> - <p class="note"><strong>Note:</strong> Be sure to define - a target for your AVD that satisfies your application's build target (the AVD - platform target must have an API Level equal to or greater than the API Level that your -application compiles against).</p> - </li> - <li>Click <strong>Create AVD</strong>.</li> -</ol> - -<p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or -launch an emulator with the AVD by clicking <strong>Start</strong>.</p> - -<p>For more information about AVDs, read the -<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> -documentation.</p> - - -<h2 id="Running">Running Your Application</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Use the Emulator to Test Different Configurations</h2> -<p>Create multiple AVDs that each define a different device configuration with which your -application is compatible, then launch each AVD into a new emulator from the SDK and AVD Manager. -Set the target mode in your app's run configuration to manual, so that when you run your -application, you can select from the available virtual devices.</p> -</div> -</div> - -<p>Running your application on a virtual or real device takes just a couple steps. Remember to -first <a href="#Building">build your application</a>.</p> - -<h3 id="RunningOnEmulator">Running on the emulator</h3> - -<p>Before you can run your application on the Android Emulator, -you must <a href="#AVD">create an AVD</a>.</p> - -<p>To run your application:</p> -<ol> - <li><strong>Open the SDK and AVD Manager and launch a virtual device</strong></li> - <p>From your SDK's <code>tools/</code> directory, execute the {@code android} tool with no -arguments: - <pre>android</pre> - <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> - </li> - - <li><strong>Install your application</strong> - <p>From your SDK's <code>platform-tools/</code> directory, install the {@code .apk} on the -emulator: - <pre>adb install <em><path_to_your_bin></em>.apk</pre> - <p>Your APK file (signed with either a release or debug key) is in your project {@code bin/} -directory after you <a href="#Building">build your application</a>.</p> - <p>If there is more than one emulator running, you must specify the emulator upon which to -install the application, by its serial number, with the <code>-s</code> option. For example:</p> - <pre>adb -s emulator-5554 install <em>path/to/your/app</em>.apk</pre> - <p>To see a list of available device serial numbers, execute {@code adb devices}.</p> - </li> -</ol> - -<p>If you don't see your application on the emulator. Try closing the emulator and launching the -virtual device again from the SDK and AVD Manager. Sometimes when you install an Activity for the -first time, it won't show up in the application launcher or be accessible by other -applications. This is because the package manager usually examines manifests -completely only on emulator startup.</p> - -<p>Be certain to create multiple AVDs upon which to test your application. You should have one AVD -for each platform and screen type with which your application is compatible. For -instance, if your application compiles against the Android 1.5 (API Level 3) platform, you should -create an AVD for each platform equal to and greater than 1.5 and an AVD for each <a -href="{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test -your application on each one.</p> - -<p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, -you can build your application and install it on the emulator in one simple step. -Navigate to the root of your project directory and use Ant to compile the project -with <em>install mode</em>: -<code>ant install</code>. This will build your application, sign it with the debug key, -and install it on the currently running emulator.</p> - - -<h3 id="RunningOnDevice">Running on a device</h3> - -<p>Before you can run your application on a device, you must perform some basic setup for your -device:</p> - -<ul> - <li>Declare your application as debuggable in your manifest</li> - <li>Enable USB Debugging on your device</li> - <li>Ensure that your development computer can detect your device when connected via USB</li> -</ul> -<p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for -Development</a> for more information.</p> - -<p>Once your device is set up and connected via USB, navigate to your -SDK's <code>platform-tools/</code> directory and install the <code>.apk</code> on the device: - <pre>adb -d install <em>path/to/your/app</em>.apk</pre> - <p>The {@code -d} flag specifies that you want to use the attached device (in case you also -have an emulator running).</p> - -<p>For more information on the tools used above, please see the following documents:</p> -<ul> - <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> - <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> - <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li> -</ul> - -<h2 id="libraryProject">Working with Library Projects</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Library project example code</h2> - -<p>The SDK includes an example application called TicTacToeMain that shows how a -dependent application can use code and resources from an Android Library -project. The TicTacToeMain application uses code and resources from an example -library project called TicTacToeLib. - -<p style="margin-top:1em;">To download the sample applications and run them as -projects in your environment, use the <em>Android SDK and AVD Manager</em> to -download the "Samples for SDK API 8" component into your SDK. </p> - -<p style="margin-top:1em;">For more information and to browse the code of the -samples, see the <a -href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain -application</a>.</p> -</div> -</div> - -<p>An Android <em>library project</em> is a development project that holds -shared Android source code and resources. Other Android application projects can -reference the library project and, at build time, include its compiled sources -in their <code>.apk</code> files. Multiple application projects can reference -the same library project and any single application project can reference -multiple library projects. </p> - -<p>If you have source code and resources that are common to multiple application -projects, you can move them to a library project so that it is easier to -maintain across applications and versions. Here are some common scenarios in -which you could make use of library projects: </p> - -<ul> -<li>If you are developing multiple related applications that use some of the -same components, you could move the redundant components out of their respective -application projects and create a single, reuseable set of the same components -in a library project. </li> -<li>If you are creating an application that exists in both free and paid -versions, you could move the part of the application that is common to both versions -into a library project. The two dependent projects, with their different package -names, will reference the library project and provide only the difference -between the two application versions.</li> -</ul> - -<p>Structurally, a library project is similar to a standard Android application -project. For example, it includes a manifest file at the project root, as well -as <code>src/</code>, <code>res/</code> and similar directories. The project can -contain the same types of source code and resources as a standard -Android project, stored in the same way. For example, source code in the library -project can access its own resources through its <code>R</code> class. </p> - -<p>However, a library project differs from an standard Android application -project in that you cannot compile it directly to its own <code>.apk</code> or -run it on the Android platform. Similarly, you cannot export the library project -to a self-contained JAR file, as you would do for a true library. Instead, you -must compile the library indirectly, by referencing the library from a dependent -application's build path, then building that application. </p> - -<p>When you build an application that depends on a library project, the SDK -tools compile the library and merge its sources with those in the main project, -then use the result to generate the <code>.apk</code>. In cases where a resource -ID is defined in both the application and the library, the tools ensure that the -resource declared in the application gets priority and that the resource in the -library project is not compiled into the application <code>.apk</code>. This -gives your application the flexibility to either use or redefine any resource -behaviors or values that are defined in any library.</p> - -<p>To organize your code further, your application can add references to -multiple library projects, then specify the relative priority of the resources -in each library. This lets you build up the resources actually used in your -application in a cumulative manner. When two libraries referenced from an -application define the same resource ID, the tools select the resource from the -library with higher priority and discard the other. - -<p>Once you've have added references, the tools let you set their relative -priority by editing the application project's build properties. At build time, -the tools merge the libraries with the application one at a time, starting from -the lowest priority to the highest. </p> - -<p>Note that a library project cannot itself reference another library project -and that, at build time, library projects are <em>not</em> merged with each -other before being merged with the application. However, note that a library can -import an external library (JAR) in the normal way.</p> - -<p>The sections below describe how to use ADT to set up and manage library your -projects. Once you've set up your library projects and moved code into them, you -can import library classes and resources to your application in the normal way. -</p> - - -<h3 id="libraryReqts">Development requirements</h3> - -<p>Android library projects are a build-time construct, so you can use them to -build a final application <code>.apk</code> that targets any API level and is -compiled against any version of the Android library. </p> - -<p>However, to use library projects, you need to update your development -environment to use the latest tools and platforms, since older releases of the -tools and platforms do not support building with library projects. Specifically, -you need to download and install the versions listed below:</p> - -<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools -and plaforms on which you can develop library projects.</p> - -<table> -<tr> -<th>Component</th> -<th>Minimum Version</th> -</tr> -<tr> -<td>SDK Tools</td> -<td>r6 (or higher)</td> -</tr> -<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> -<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> -<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> -<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> -<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> -<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> -</table> - -<p>You can download the tools and platforms using the <em>Android SDK and AVD -Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK -Components</a>.</p> - - -<h3 id="librarySetup">Setting up a new library project</h3> - -<p>A library project is a standard Android project, so you can create a new one in the -same way as you would a new application project. Specifically, you can use -the <code>android</code> tool to generate a new library project with all of the -necessary files and folders. </p> - -<h4>Creating a library project</h4> - -<p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory -and use this command:</p> - -<pre class="no-pretty-print" style="color:black"> -android create lib-project --name <em><your_project_name></em> \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> \ ---package <em><your_library_package_namespace></em> -</pre> - -<p>The <code>create lib-project</code> command creates a standard project -structure that includes preset property that indicates to the build system that -the project is a library. It does this by adding this line to the project's -<code>default.properties</code> file: </p> - -<pre class="no-pretty-print" style="color:black">android.library=true</pre> - -<p>Once the command completes, the library project is created and you can begin moving -source code and resources into it, as described in the sections below.</p> - -<p>If you want to convert an existing application project to a library project, -so that other applications can use it, you can do so by adding a the -<code>android.library=true</code> property to the application's -<code>default.properties</code> file. </p> - -<h4>Creating the manifest file</h4> - -<p>A library project's manifest file must declare all of the shared components -that it includes, just as would a standard Android application. For more -information, see the documentation for <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> - -<p>For example, the <a -href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> -example library project declares the Activity <code>GameActivity</code>: </p> - -<pre><manifest> - ... - <application> - ... - <activity android:name="GameActivity" /> - ... - </application> -</manifest></pre> - -<h4>Updating a library project</h4> - -<p>If you want to update the build properties (build target, location) of the -library project, use this command: </p> - -<pre> -android update lib-project \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> -</pre> - - -<h3 id="libraryReference">Referencing a library project from an application</h3> - -<p>If you are developing an application and want to include the shared code or -resources from a library project, you can do so easily by adding a reference to -the library project in the application project's build properties.</p> - -<p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code> directory -and use this command:</p> - -<pre> -android update lib-project \ ---target <em><target_ID></em> \ ---path <em>path/to/your/project</em> ---library <em>path/to/library_projectA</em> -</pre> - -<p>This command updates the application project's build properties to include a -reference to the library project. Specifically, it adds an -<code>android.library.reference.<em>n</em></code> property to the project's -<code>default.properties</code> file. For example: </p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.1=path/to/library_projectA -</pre> - -<p>If you are adding references to multiple libraries, note that you can set -their relative priority (and merge order) by manually editing the -<code>default.properties</code> file and adjusting the each reference's -<code>.<em>n</em></code> index as appropriate. For example, assume these -references: </p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.1=path/to/library_projectA -android.library.reference.2=path/to/library_projectB -android.library.reference.3=path/to/library_projectC -</pre> - -<p>You can reorder the references to give highest priority to -<code>library_projectC</code> in this way:</p> - -<pre class="no-pretty-print" style="color:black"> -android.library.reference.2=path/to/library_projectA -android.library.reference.3=path/to/library_projectB -android.library.reference.1=path/to/library_projectC -</pre> - -<p>Note that the <code>.<em>n</em></code> index in the references -must begin at "1" and increase uniformly without "holes". References -appearing in the index after a hole are ignored. </p> - -<p>At build time, the libraries are merged with the application one at a time, -starting from the lowest priority to the highest. Note that a library cannot -itself reference another library and that, at build time, libraries are not -merged with each other before being merged with the application.</p> - - -<h4>Declaring library components in the the manifest file</h4> - -<p>In the manifest file of the application project, you must add declarations -of all components that the application will use that are imported from a library -project. For example, you must declare any <code><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="depAppBuild">Building a dependent application</h3> - -<p>To build an application project that depends on one or more library projects, -you can use the standard Ant build commands and compile modes, as described in -<a href="#Building">Building Your Application</a>, earlier in this document. The -tools compile and merge all libraries referenced by the application as part -of compiling the dependent application project. No additional commands or steps -are necessary. </p> - -<h3 id="considerations">Development considerations</h3> - -<p>As you develop your library project and dependent applications, keep the -points listed below in mind.</p> - -<p><strong>Resource conflicts</strong></p> - -<p>Since the tools merge the resources of a library project with those of a -dependent application project, a given resource ID might be defined in both -projects. In this case, the tools select the resource from the application, or -the library with highest priority, and discard the other resource. As you -develop your applications, be aware that common resource IDs are likely to be -defined in more than one project and will be merged, with the resource from the -application or highest-priority library taking precedence.</p> - -<p><strong>Using prefixes to avoid resource conflicts</strong></p> - -<p>To avoid resource conflicts for common resource IDs, consider using a prefix -or other consistent naming scheme that is unique to the project (or is unique -across all projects). </p> - -<p><strong>No export of library project to JAR</strong></p> - -<p>A library cannot be distributed as a binary file (such as a jar file). This -is because the library project is compiled by the main project to use the -correct resource IDs.</p> - -<p><strong>A library project can include a JAR library</strong></p> - -<p>You can develop a library project that itself includes a JAR library. When -you build the dependent application project, the tools automatically locate and -include the library in the application <code>.apk</code>. </p> - -<p><strong>A library project can depend on an external JAR library</strong></p> - -<p>You can develop a library project that depends on an external library (for -example, the Maps external library). In this case, the dependent application -must build against a target that includes the external library (for example, the -Google APIs Add-On). Note also that both the library project and the dependent -application must declare the external library their manifest files, in a <a -href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a> -element. </p> - -<p><strong>Library project cannot include raw assets</strong></p> - -<p>The tools do not support the use of raw asset files in a library project. -Any asset resources used by an application must be stored in the -<code>assets/</code> directory of the application project -itself.</p> - -<p><strong>Targeting different Android platform versions in library project and -application project</strong></p> - -<p>A library is compiled as part of the dependent application project, so the -API used in the library project must be compatible with the version of the -Android library used to compile the application project. In general, the library -project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a> -that is the same as — 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> - -<h2 id="AttachingADebugger">Attaching a Debugger to Your Application</h2> - -<p>This section describes how to display debug information on the screen (such - as CPU usage), as well as how to hook up your IDE to debug running applications - on the emulator. </p> - -<p>Attaching a debugger is automated using the Eclipse plugin, - but you can configure other IDEs to listen on a debugging port to receive debugging - information:</p> -<ol> - <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor - Server (DDMS)</a> tool, </strong> which - acts as a port forwarding service between your IDE and the emulator.</li> - <li><strong>Set - optional debugging configurations on - your emulator</strong>, such as blocking application startup for an Activity - until a debugger is attached. Note that many of these debugging options - can be used without DDMS, such as displaying CPU usage or screen refresh - rate on the emulator.</li> - <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> Read - about <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> - Configuring Your IDE to Attach to the Debugging Port</a>. </li> -</ol> |