Merge "Doc change: documentation for library projects in sdk." into froyo

5 files changed, 811 insertions, 20 deletions

diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd
index 549e093..cf2a457 100644
--- a/docs/html/guide/developing/eclipse-adt.jd
+++ b/docs/html/guide/developing/eclipse-adt.jd
@@ -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>
@@ -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 
@@ -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
@@ -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>&lt;manifest&gt;
+  ...
+  &lt;application&gt;
+    ...
+    &lt;activity android:name="GameActivity" /&gt;
+    ...
+  &lt;/application&gt;
+  ...
+&lt;/manifest&gt;</pre>
+
+
+<h3 id="libraryReference">Referencing a library project from an application</h3>
+
+<p>If you are developing an application and want to include the shared code or
+resources from a library project, you can do so easily by adding a reference to
+the library project in the application project's Properties.</p>
+
+<p>To add a reference to a library project, follow these steps: </p>
+
+<ol>
+<li>In the <strong>Package Explorer</strong>, right-click the dependent project
+and select <strong>Properties</strong>.</li>
+<li>In the <strong>Properties</strong> window, select the "Android" properties group
+at left and locate the <strong>Library</strong> properties at right.</li>
+<li>Click <strong>Add</strong> to open the <strong>Project Selection</strong>
+dialog. </li>
+<li>From the list of available library projects, select a project and click
+<strong>OK</strong>.</li>
+<li>When the dialog closes, click <strong>Apply</strong> in the
+<strong>Properties</strong> window.</li>
+<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
+</ol>
+
+<p>As soon as the Properties dialog closes, Eclipse rebuilds the project,
+including the contents of the library project. </p>
+
+<p>The figure below shows the Properties dialog that lets you add library
+references and move them up and down in priority. </p>
+
+<img src="{@docRoot}images/developing/adt-props-libRef.png" style="margin:0;padding:0;" />
+<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 2.</strong>
+Adding a reference to a library project in the properties of an application project. </p>
+
+<p>If you are adding references to multiple libraries, note that you can set
+their relative priority (and merge order) by selecting a library and using the
+<strong>Up</strong> and <strong>Down</strong> controls. The tools merge the
+referenced libraries with your application starting from lowest priority (bottom
+of the list) to highest (top of the list). If more than one library defines the
+same resource ID, the tools select the resource from the library with higher
+priority. The application itself has highest priority and its resources are
+always used in preference to identical resource IDs defined in libraries.</p>
+
+<h4>Declaring library components in the the manifest file</h4>
+
+<p>In the manifest file of the application project, you must add declarations
+of all components that the application will use that are imported from a library
+project. For example, you must declare any <code>&lt;activity&gt;</code>,
+<code>&lt;service&gt;</code>, <code>&lt;receiver&gt;</code>,
+<code>&lt;provider&gt;</code>, and so on, as well as
+<code>&lt;permission&gt;</code>, <code>&lt;uses-library&gt;</code>, and similar
+elements.</p>
+
+<p>Declarations should reference the library components by their fully-qualified
+package names, where appropriate. </p>
+
+<p>For example, the <a 
+href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a>
+example application declares the library Activity <code>GameActivity</code>
+like this: </p>
+
+<pre>&lt;manifest&gt;
+  ...
+  &lt;application&gt;
+    ...
+    &lt;activity android:name="com.example.android.tictactoe.library.GameActivity" /&gt;
+    ...
+  &lt;/application&gt;
+  ...
+&lt;/manifest&gt;</pre>
+
+<p>For more information about the manifest file, see the documentation for <a href="{@docRoot}guide/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>&lt;uses-library&gt;</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 &mdash; or lower than &mdash; that used by the application.
+If the library project uses an API level that is higher than that of the
+application, the application project will fail to compile. It is perfectly
+acceptable to have a library that uses the Android 1.5 API (API level 3) and
+that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7)
+project, for instance.</p>
+
+<p><strong>No restriction on library package name</strong></p>
+
+<p>There is no requirement for the package name of a library to be the same as
+that of applications that use it.</p>
+
+<p><strong>Multiple R classes in gen/ folder of application project</strong></p>
+
+<p>When you build the dependent application project, the code of any libraries
+is compiled and merged to the application project. Each library has its own
+<code>R</code> class, named according to the library's package name. The
+<code>R</code> class generated from the resources of the main project and of the
+library is created in all the packages that are needed including the main
+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>
diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd
index 76b2d9f..e8a6fb6 100644
--- a/docs/html/guide/developing/other-ide.jd
+++ b/docs/html/guide/developing/other-ide.jd
@@ -20,6 +20,15 @@ page.title=Developing In Other IDEs
         <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>
 
@@ -93,7 +102,7 @@ navigate to the <code>tools/</code> directory of your SDK and run:</p>
 android create project \
 --target <em>&lt;target_ID&gt;</em> \
 --name <em>&lt;your_project_name&gt;</em> \
---path <em>/path/to/your/project</em> \
+--path <em>path/to/your/project</em> \
 --activity <em>&lt;your_activity_name&gt;</em> \
 --package <em>&lt;your_package_namespace&gt;</em>
 </pre>
@@ -350,7 +359,7 @@ root of the project directory) and add entries for {@code key.store} and {@code
 For example:</p>
 
 <pre>
-key.store=/path/to/my.keystore
+key.store=path/to/my.keystore
 key.alias=mykeystore
 </pre>
 
@@ -458,7 +467,7 @@ emulator:
 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>
+    <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>
@@ -499,12 +508,10 @@ Development</a> for more information.</p>
 
 <p>Once your device is set up and connected via USB, navigate to your
 SDK's <code>tools/</code> directory and install the <code>.apk</code> on the device:
-    <pre>adb -d install <em>/path/to/your/app</em>.apk</pre>
+    <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>
@@ -512,6 +519,409 @@ have an emulator running).</p>
   <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 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>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>&lt;sdk&gt;/tools/</code> directory
+and use this command:</p>
+
+<pre class="no-pretty-print" style="color:black">
+android create lib-project --name <em>&lt;your_project_name&gt;</em> \
+--target <em>&lt;target_ID&gt;</em> \
+--path <em>path/to/your/project</em> \
+--package <em>&lt;your_library_package_namespace&gt;</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/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+<p>For example, the <a
+href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a>
+example library project declares the Activity <code>GameActivity</code>: </p>
+
+<pre>&lt;manifest&gt;
+  ...
+  &lt;application&gt;
+    ...
+    &lt;activity android:name="GameActivity" /&gt;
+    ...
+  &lt;/application&gt;
+  ...
+&lt;/manifest&gt;</pre>
+
+<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>&lt;target_ID&gt;</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>&lt;sdk&gt;/tools/</code> directory
+and use this command:</p>
+
+<pre>
+android update lib-project \
+--target <em>&lt;target_ID&gt;</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>&lt;activity&gt;</code>,
+<code>&lt;service&gt;</code>, <code>&lt;receiver&gt;</code>,
+<code>&lt;provider&gt;</code>, and so on, as well as
+<code>&lt;permission&gt;</code>, <code>&lt;uses-library&gt;</code>, and similar
+elements.</p>
+
+<p>Declarations should reference the library components by their fully-qualified
+package names, where appropriate. </p>
+
+<p>For example, the 
+<a href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a>
+example application declares the library Activity <code>GameActivity</code>
+like this: </p>
+
+<pre>&lt;manifest&gt;
+  ...
+  &lt;application&gt;
+    ...
+    &lt;activity android:name="com.example.android.tictactoe.library.GameActivity" /&gt;
+    ...
+  &lt;/application&gt;
+  ...
+&lt;/manifest&gt;</pre>
+
+<p>For more information about the manifest file, see the documentation for <a href="{@docRoot}guide/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>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. 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>&lt;uses-library&gt;</code></a>
+element. </p>
+
+<p><strong>Library project cannot 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 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 &mdash; or lower than &mdash; that used by the application.
+If the library project uses an API level that is higher than that of the
+application, the application project will fail to compile. It is perfectly
+acceptable to have a library that uses the Android 1.5 API (API level 3) and
+that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7)
+project, for instance.</p>
+
+<p><strong>No restriction on library package name</strong></p>
+
+<p>There is no requirement for the package name of a library to be the same as
+that of applications that use it.</p>
+
+<p><strong>Multiple R classes in gen/ folder of application project</strong></p>
+
+<p>When you build the dependent application project, the code of any libraries
+is compiled and merged to the application project. Each library has its own
+<code>R</code> class, named according to the library's package name. The
+<code>R</code> class generated from the resources of the main project and of the
+library is created in all the packages that are needed including the main
+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>
 
diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd
index 1e254f0..45e3e49 100644
--- a/docs/html/guide/practices/screens_support.jd
+++ b/docs/html/guide/practices/screens_support.jd
@@ -35,7 +35,7 @@ page.title=Supporting Multiple Screens
   <ol>
     <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
     <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</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>
 
@@ -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>
 
@@ -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>
@@ -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&lt;api-level&gt;</code>
diff --git a/docs/html/images/developing/adt-props-isLib.png b/docs/html/images/developing/adt-props-isLib.png
new file mode 100644
index 0000000..18bdb33
--- /dev/null
+++ b/docs/html/images/developing/adt-props-isLib.png
diff --git a/docs/html/images/developing/adt-props-libRef.png b/docs/html/images/developing/adt-props-libRef.png
new file mode 100644
index 0000000..e61df51
--- /dev/null
+++ b/docs/html/images/developing/adt-props-libRef.png