Merge "Doc change: fixing errors in library proj docs" into honeycomb

        <li><a href="#LibraryProjects">Library Projects</a>

          <ol>

            <li><a href="#libraryMigrating">Migrating library projects to ADT 0.9.8 or higher</a></li>

            <li><a href="#considerations">Development considerations</a></li>

          </ol>

        </li>

        <li><a href="#TestProjects">Test Projects</a></li>

        <li><a href="#testing">Testing a Library Project</a></li>

      </ol>

    </div>

  </div>

    application projects can reference the same library project and any single application project

    can reference multiple library projects.</p>

    <p class="note"><strong>Note:</strong> You need SDK Tools r8 or newer to fully support library projects

    for all Android platform versions. 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>

    <p>If you have source code and resources that are common to multiple Android 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>

    the application. However, note that a library can import an external library (JAR) 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 platforms 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="considerations">Development considerations</h3>

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

  <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></li>

  <li><p><strong>One library project cannot reference another</strong></p>

  <p>A library cannot depend on another library</p></li>

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

  files, in a <a href=

  "{@docRoot}guide/topics/manifest/uses-library-element.html"><code>&lt;uses-library&gt;</code></a>

  element.</p></li>

  <li><p><strong>Library project cannot include AIDL files</strong></p>

  <p>The tools do not support the use of AIDL files in a library project. Any AIDL files used by an

  application must be stored in the application project itself.</p></li>

  <li> <p><strong>Library projects cannot include raw assets</strong></p>

  project can reference the library project through a relative link.</p></li>

  </ul>

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

<p>This section provides information about how to migrate a library project

created with ADT 0.9.7 to ADT 0.9.8 or higher. The migration is needed only if

you are developing in Eclipse with ADT and assumes that you have also upgraded

to SDK Tools r7 (or higher). </p> 

<p>The way that ADT handles library projects has changed between

ADT 0.9.7 and ADT 0.9.8. Specifically, in ADT 0.9.7, the <code>src/</code> 

source folder of the library was linked into the dependent application project

as a folder that had the same name as the library project. This worked because

of two restrictions on the library projects:</p> 

<ul> 

<li>The library was only able to contain a single source folder (excluding the

special <code>gen/</code> source folder), and</li> 

<li>The source folder was required to have the name <code>src/</code> and be

stored at the root of the project.</li> 

</ul> 

<p>In ADT 0.9.8, both of those restrictions were removed. A library project can

have as many source folders as needed and each can have any name. Additionally,

a library project can store source folders in any location of the project. For

example, you could store sources in a <code>src/java/</code> directory. In order

to support this, the name of the linked source folders in the main project are

now called <library-name>_<folder-name> For

example: <code>MyLibrary_src/</code> or <code>MyLibrary_src_java/</code>.</p> 

<p>Additionally, the linking process now flags those folders in order for ADT to

recognize that it created them. This will allow ADT to automatically migrate the

project to new versions of ADT, should they contain changes to the handling of

library projects. ADT 0.9.7 did not flag the linked source folders, so ADT 0.9.8

cannot be sure whether the old linked folders can be removed safely. After

upgrading ADT to 0.9.8, you will need to remove the old linked folders manually

in a simple two-step process, as described below.</p> 

<p>Before you begin, make sure to create a backup copy of your application or

save the latest version to your code version control system. This ensures that

you will be able to easily revert the migration changes in case there is a

problem in your environment.</p> 

<p>When you first upgrade to ADT 0.9.8, your main project will look as shown

in figure 1, with two linked folders (in this example, <code>MyLibrary</code> and

<code>MyLibrary_src</code> &mdash; both of which link to

<code>MyLibrary/src</code>. Eclipse shows an error on one of them because they

are duplicate links to a single class.</p> 

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

<p class="img-caption"><strong>Figure 1.</strong> Library project migration error</p>

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

<code>_src</code> suffix. </p> 

<ol> 

<li>Right click the folder that you want to remove (in this case, the

<code>MyLibrary</code> folder) and choose <strong>Build Path</strong> &gt;

<strong>Remove from Build Path</strong>, as shown in figure 2.</li> 

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

alt=""> 

<p class="img-caption"><strong>Figure 2.</strong> Remove from Build Path menu item</p>

<li>Next, when asked about unlinking the folder from the project, select

<strong>Yes</strong>, as shown in figure 3.</li> 

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

<p class="img-caption"><strong>Figure 3.</strong> Unlink folder confirmation window</p>

</ol> 

<p>This should resolve the error and migrate your library project to the new

ADT environment. </p> 

  <h2 id="TestProjects">Test Projects</h2>

  <p>Test projects contain Android applications that you write using the 

  "{@docRoot}guide/developing/testing/index.html">Testing</a> section.

  <h2>Testing a library project</h2>

  <h2 id="testing">Testing a Library Project</h2>

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

  project:</p>