Loading docs/html/guide/developing/eclipse-adt.jd +386 −5 Original line number Diff line number Diff line Loading @@ -15,6 +15,14 @@ page.title=Developing In Eclipse, with ADT </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> </ol> </li> <li><a href="#Tips">Eclipse Tips</a></li> </div> </div> Loading Loading @@ -118,12 +126,11 @@ folders and files in your new project:</p> <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. See <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> <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">Resources and Assets</a>.</dd> <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 Loading Loading @@ -303,8 +310,7 @@ document.</p> <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> 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 Loading Loading @@ -349,6 +355,381 @@ and what it means to you as an Android application developer. The document also 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 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 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/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/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>One library project cannot reference another</strong></p> <p>A library cannot depend on another library.</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 AIDL files</strong></p> <p>The tools do not support the use of <a href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> files in a library project. Any AIDL files used by an application must be stored in the application project itself.</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> <h2 id="Tips">Eclipse Tips </h2> <h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3> Loading docs/html/guide/developing/other-ide.jd +416 −6 File changed.Preview size limit exceeded, changes collapsed. Show changes docs/html/guide/practices/screens_support.jd +9 −9 Original line number Diff line number Diff line Loading @@ -35,7 +35,7 @@ page.title=Supporting Multiple Screens <ol> <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li> <li><a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">Alternate Resources</a></li> <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Alternative Resources</a></li> <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li> </ol> Loading Loading @@ -279,16 +279,16 @@ href="{@docRoot}guide/resources/dashboard/screen-densities.html">Screen Densitie <div class="sidebox-wrapper"> <div class="sidebox"> <h2>Using the alternate resources framework</h2> <h2>Using the alternative resources framework</h2> <p>The platform's support for loading screen size- and density-specific resources at run time is based on the alternate resources framework. resources at run time is based on the alternative resources framework. <p> If you want to use size- or density-specific layouts or drawables in your application and you are not familiar with resource qualifiers or how the platform uses them, please read <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a>. <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a>. </div> </div> Loading Loading @@ -738,8 +738,8 @@ res/drawable-nodpi/composite.xml // density independent resource <p>For more information about how to use resource qualifiers or how the platform selects them, please read <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a>.</p> <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a>.</p> <h2 id="screen-independence">Best practices for Screen Independence</h2> Loading Loading @@ -1023,8 +1023,8 @@ scaling.</li> <li>Creating any size- or density-specific resources you need and placing them in directories tagged with the <a href="#qualifiers">correct qualifiers</a>. Qualifiers must be arranged in a proscribed order. See <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a> for more information. </li> <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a> for more information. </li> <li>Note that if you add size- or density-specific resource directories tagged with any of the resource qualifiers listed in this document, you should make sure to also tag those directories with the <code>v<api-level></code> Loading docs/html/images/developing/adt-props-isLib.png 0 → 100644 +100 KiB Loading image diff... docs/html/images/developing/adt-props-libRef.png 0 → 100644 +111 KiB Loading image diff... Loading
docs/html/guide/developing/eclipse-adt.jd +386 −5 Original line number Diff line number Diff line Loading @@ -15,6 +15,14 @@ page.title=Developing In Eclipse, with ADT </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> </ol> </li> <li><a href="#Tips">Eclipse Tips</a></li> </div> </div> Loading Loading @@ -118,12 +126,11 @@ folders and files in your new project:</p> <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. See <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> <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">Resources and Assets</a>.</dd> <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 Loading Loading @@ -303,8 +310,7 @@ document.</p> <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> 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 Loading Loading @@ -349,6 +355,381 @@ and what it means to you as an Android application developer. The document also 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 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 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/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/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>One library project cannot reference another</strong></p> <p>A library cannot depend on another library.</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 AIDL files</strong></p> <p>The tools do not support the use of <a href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> files in a library project. Any AIDL files used by an application must be stored in the application project itself.</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> <h2 id="Tips">Eclipse Tips </h2> <h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3> Loading
docs/html/guide/developing/other-ide.jd +416 −6 File changed.Preview size limit exceeded, changes collapsed. Show changes
docs/html/guide/practices/screens_support.jd +9 −9 Original line number Diff line number Diff line Loading @@ -35,7 +35,7 @@ page.title=Supporting Multiple Screens <ol> <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li> <li><a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">Alternate Resources</a></li> <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Alternative Resources</a></li> <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li> </ol> Loading Loading @@ -279,16 +279,16 @@ href="{@docRoot}guide/resources/dashboard/screen-densities.html">Screen Densitie <div class="sidebox-wrapper"> <div class="sidebox"> <h2>Using the alternate resources framework</h2> <h2>Using the alternative resources framework</h2> <p>The platform's support for loading screen size- and density-specific resources at run time is based on the alternate resources framework. resources at run time is based on the alternative resources framework. <p> If you want to use size- or density-specific layouts or drawables in your application and you are not familiar with resource qualifiers or how the platform uses them, please read <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a>. <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a>. </div> </div> Loading Loading @@ -738,8 +738,8 @@ res/drawable-nodpi/composite.xml // density independent resource <p>For more information about how to use resource qualifiers or how the platform selects them, please read <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a>.</p> <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a>.</p> <h2 id="screen-independence">Best practices for Screen Independence</h2> Loading Loading @@ -1023,8 +1023,8 @@ scaling.</li> <li>Creating any size- or density-specific resources you need and placing them in directories tagged with the <a href="#qualifiers">correct qualifiers</a>. Qualifiers must be arranged in a proscribed order. See <a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> Alternate Resources</a> for more information. </li> <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Alternative Resources</a> for more information. </li> <li>Note that if you add size- or density-specific resource directories tagged with any of the resource qualifiers listed in this document, you should make sure to also tag those directories with the <code>v<api-level></code> Loading
