Merge "Update dev guide for new build system and new lib system."

        <li><a href="#RunningOnEmulator">Running on the Emulator</a></li>

        <li><a href="#RunningOnDevice">Running on a Device</a></li>

        <li><a href="#Signing">Application Signing</a></li>

        <li><a href="#AntReference">Ant Command Reference</a></li>

      </ol>

  <h2>See also</h2>

  <ol>

  <p>If you would like, you can configure the Android build script to automatically sign and align

  your application package. To do so, you must provide the path to your keystore and the name of

  your key alias in your project's {@code build.properties} file. With this information provided,

  your key alias in your project's {@code ant.properties} file. With this information provided,

  the build script will prompt you for your keystore and alias password when you build in release

  mode and produce your final application package, which will be ready for distribution.</p>

  procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with

  <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>

  <p>To specify your keystore and alias, open the project {@code build.properties} file (found in

  <p>To specify your keystore and alias, open the project {@code ant.properties} file (found in

  the root of the project directory) and add entries for {@code key.store} and {@code key.alias}.

  For example:</p>

  <pre>

  <p>This creates your Android application .apk file inside the project <code>bin/</code>

  directory, named <code><em>&lt;your_project_name&gt;</em>-release.apk</code>. This .apk file has

  been signed with the private key specified in {@code build.properties} and aligned with {@code

  been signed with the private key specified in {@code ant.properties} and aligned with {@code

  zipalign}. It's ready for installation and distribution.</p>

  <h3 id="OnceBuilt">Once built and signed in release mode</h3>

  device:</p>

  <ul>

    <li>Ensure that your application is debuggable by setting the

    <code>android:debuggable</code> attribute of the <code>&lt;application&gt;</code>

    element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>

    <li>Enable USB Debugging on your device. You can find the setting on most Android devices by

    going to <strong>Settings > Applications > Development > USB debugging</strong>.</li>

  Applications</a>, which provides a thorough guide to application signing on Android and what it

  means to you as an Android application developer. The document also includes a guide to exporting

  and signing your application with the ADT's Export Wizard.</p>

  <h2 id="AntReference">Ant Command Reference</h2>

  <dt><code>ant clean</code></dt>

  <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code>

(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a

test project, the tested project is also cleaned.</dd>

  <dt><code>ant debug</code></dt>

  <dd>Builds a debug package. Works on application, library, and test projects and compiles

  dependencies as  needed.</dd>

  <dt id="emma"><code>ant emma debug</code></dt>

  <dd>Builds a test project while building the tested project with instrumentation turned on.

  This is used to run tests with code coverage enabled.</dd>

  <dt><code>ant release</code></dt>

  <dd>Builds a release package.</dd>

  <dt><code>ant instrument</code>

  </dt>

  <dd>Builds an instrumented debug package. This is generally called automatically when building a

  test project with code coverage enabled (with the <code>emma</code>

  target)</dd>

  <dt><code>ant &lt;build_target&gt; install</code></dt>

  <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd>

  <dt><code>ant installd</code></dt>

  <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not

  already built.</dd>

  <dt><code>ant installr</code></dt>

  <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not

  already built.</dd>

  <dt><code>ant installt</code></dt>

  <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the

  tested application. This fails if the <code>.apk</code> is not already built.</dd>

  <dt><code>ant installi</code></dt>

  <dd>Installs an already compiled instrumented package. This is generally not used manually as

  it's called when installing a test package. This fails if the <code>.apk</code> is not already

  built.</dd>

   <dt><code>ant test</code></dt>

   <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be

   previously installed.</dd>

  <dt><code>ant debug installt test</code></dt>

  <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and

  runs the tests.</dd>

  <dt><code>ant emma debug installt test</code></dt>

  <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and

  runs the tests with code coverage enabled.</dd>

    <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>

    documentation for more information</dd>

    <dt><code>build.properties</code></dt>

    <dt><code>project.properties</code></dt>

    <dd>This file contains project settings, such as the build target. This file is integral to

    the project, so maintain it in a source revision control system. To edit project

    properties in Eclipse, right-click the project folder and select

    <strong>Properties</strong>.</dd>

    <dt><code>local.properties</code></dt>

    <dd>Customizable computer-specific properties for the build system. If you use Ant to build

    the project, this contains the path to the SDK installation. Because the content of the file

    is specific to the local installation of the SDK, maintained it in a source

    revision control system. If you use Eclipse, this file is not used.</dd>

    <dt><code>ant.properties</code></dt>

    <dd>Customizable properties for the build system. You can edit this file to override default

    build settings used by Ant and provide a pointer to your keystore and key alias so that the

    build tools can sign your application when built in release mode. If you use Eclipse, this file

    is not used.</dd>

    build settings used by Ant and also provide the location of your keystore and key alias so that

    the build tools can sign your application when building in release mode. This file is integral

    to the project, so maintain it in a source revision control system. If you use Eclipse, this

    file is not used.</dd>

    <dt><code>build.xml</code></dt>

    <dd>The Ant build file for your project. This is only applicable for projects that

    you create on the command line.</dd>

    <dt><code>default.properties</code></dt>

    you build with Ant.</dd>

    <dd>This file contains project settings, such as the build target. This files is integral to

    the project, as such, it should be maintained in a Source Revision Control system. Do not edit

    the file manually.</dd>

  </dl>

  <h2 id="LibraryProjects">Library Projects</h2>

      <p>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>

      SDK API 8" (or later) component into your SDK.</p>

      <p>For more information and to browse the code of the samples, see

      the <a href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain

    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

    <p class="note"><strong>Note:</strong> You need SDK Tools r14 or newer to use the new library

    project feature that generates each library project into its own JAR file.

    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>

    library in the dependent application and 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>

    library into a temporary JAR file and uses it in the main project, then uses 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

    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>Library projects can reference other library projects and can import an external library

    (JAR) in the  normal way.</p>

  <h3 id="considerations">Development considerations</h3>

  <li><p><strong>You cannot export a library project to a JAR file</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></li>

  <p>A library cannot be distributed as a binary file (such as a JAR file). This will

be added in a future

  version of the SDK Tools.</p></li>

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

    <code>&lt;instrumentation&gt;</code></a>

    element that connects the test project with the application project.</dd>

    <dt><code>build.properties</code></dt>

    <dt><code>project.properties</code></dt>

    <dd>This file contains project settings, such as the build target and links to the project being

tested. This file is integral to the project, so maintain it in a source

revision control system. To edit project properties in Eclipse, right-click the project folder

and select <strong>Properties</strong>.</dd>

    <dt><code>local.properties</code></dt>

    <dd>Customizable computer-specific properties for the build system. If you use Ant to build

    the project, this contains the path to the SDK installation. Because the content of the file

    is specific to the local installation of the SDK, it should not be maintained in a Source

    Revision Control system. If you use Eclipse, this file is not used.</dd>

    <dt><code>ant.properties</code></dt>

    <dd>Customizable properties for the build system. You can edit this file to override default

    build settings used by Ant and provide a pointer to your keystore and key alias so that the

    build tools can sign your application when built in release mode.</dd>

    build settings used by Ant and provide the location to your keystore and key alias, so that the

    build tools can sign your application when building in release mode. This file is integral to

    the project, so maintain it in a source revision control system.

    If you use Eclipse, this file is not used.</dd>

    <dt><code>build.xml</code></dt>

    <dd>The Ant build file for your project.</dd>

    <dt><code>default.properties</code></dt>

    <dd>The Ant build file for your project. This is only applicable for projects that

    you build with Ant.</dd>

  </dl>

    <dd>This file contains project settings, such as the build target. This files is integral to

    the project, as such, it should be maintained in a Source Revision Control system. It should

    never be edited manually — to edit project properties, right-click the project folder and

    select "Properties".</dd>

  </dl>For more information, see the <a href=

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

  <p>For more information, see the <a href=

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

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

  to your <code>PATH</code> environment variable.</p>

  <p class="caution"><strong>Caution:</strong> You should refrain from moving the location of the

  SDK directory, because this will break the build scripts. (They will need to be manually updated

  to reflect the new SDK location before they will work again.)</p>

  SDK directory, because this will break the SDK location property located in <code>local.properties</code>.

  If you need to update the SDK location, use the <code>android update project</code> command.

  See <a href="UpdatingAProject">Updating a Project</a> for more information.</p>

  <h2 id="UpdatingAProject">Updating a Project</h2>

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

  adding this line to the project's <code>project.properties</code> file:</p>

  <pre class="no-pretty-print">

android.library=true

</pre>

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

  to the application's <code>project.properties</code> file.</p>

  <h3 id="CreatingManifestFile">Creating the manifest file</h3>

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

  property to the project's <code>project.properties</code> file. For example:</p>

  <pre class="no-pretty-print">

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

  priority (and merge order) by manually editing the <code>project.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">

  customizing the ProGuard configuration file.</p>

  <p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the

  <code>proguard.config</code> property in the <code>&lt;project_root&gt;/default.properties</code>

  <code>proguard.config</code> property in the <code>&lt;project_root&gt;/project.properties</code>

  file. The path can be an absolute path or a path relative to the project's root.</p>

<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory),

you can specify its location like this:</p>

The build scripts used

when compiling your application with Ant will also zipalign your .apk,

as long as you have provided the path to your keystore and the key alias in

your project {@code build.properties} file, so that the build tools 

your project {@code ant.properties} file, so that the build tools 

can sign the package first.</p>

<p class="caution"><strong>Caution:</strong> zipalign must only be performed