Doc change: adding Projects section of dev guide
Change-Id: I0f9a0fdd238027713bff00d4f6273e168b0dc050
diff --git a/docs/html/guide/developing/projects/index.jd b/docs/html/guide/developing/projects/index.jd
new file mode 100644
index 0000000..1daf738
--- /dev/null
+++ b/docs/html/guide/developing/projects/index.jd
@@ -0,0 +1,493 @@
+page.title=Creating and Managing Projects
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#ApplicationProjects">Android Projects</a></li>
+
+ <li><a href="#LibraryProjects">Library Projects</a></li>
+
+ <li><a href="#TestProjects">Test Projects</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Projects act as containers for storing things such as code and resource files. The SDK tools
+ expect your projects to follow a specific structure so it can compile and package your
+ application correctly, so it is highly recommended that you create them with Eclipse and ADT or
+ with the <code>android</code> tool on the command line. There are three types of projects, and
+ they all share the same general structure but differ in function:</p>
+
+ <dl>
+ <dt><strong>Android Projects</strong></dt>
+
+ <dd>An Android project is the container for your application's source code, resource files, and
+ files such as the Ant build and Android Manifest file. An application project is the main type
+ of project and the contents are eventually built into an <code>.apk</code> file that you install on a
+ device.</dd>
+
+ <dt><strong>Test Projects</strong></dt>
+
+ <dd>These projects contain code to test your application projects and are built into
+ applications that run on a device.</dd>
+
+ <dt><strong>Library Projects</strong></dt>
+
+ <dd>These projects contain shareable Android source code and resources that you can reference
+ in Android projects. This is useful when you have common code that you want to reuse.
+ Library projects cannot be installed onto a device, however, they are
+ pulled into the <code>.apk</code> file at build time.</dd>
+ </dl>
+
+ <p>When you use the Android development tools to create a new project, the essential files and
+ folders will be created for you. There are only a handful of files and folders generated for you,
+ and some of them depend on whether you use the Eclipse plugin or the {@code android} tool to
+ generate your project. As your application grows in complexity, you might require new kinds of
+ resources, directories, and files.</p>
+
+ <h2 id="ApplicationProjects">Android Projects</h2>
+
+ <p>Android projects are the projects that eventually get built into an <code>.apk</code> file that you install
+ onto a device. They contain things such as application source code and resource files.
+ Some are generated for you by default, while others should be created if
+ required. The following directories and files comprise an Android project:</p>
+
+ <dl>
+ <dt><code>src/</code></dt>
+
+ <dd>Contains your stub Activity file, which is stored at
+ <code>src<em>/your/package/namespace/ActivityName</em>.java</code>. All other source code
+ files (such as <code>.java</code> or <code>.aidl</code> files) go here as well.</dd>
+
+ <dt><code>bin</code></dt>
+
+ <dd>Output directory of the build. This is where you can find the final <code>.apk</code> file and other
+ compiled resources.</dd>
+
+ <dt><code>jni</code></dt>
+
+ <dd>Contains native code sources developed using the Android NDK. For more information, see the
+ <a href="{@docRoot}sdk/ndk/index.html">Android NDK documentation</a>.</dd>
+
+ <dt><code>gen/</code></dt>
+
+ <dd>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. Files that you save here are
+ compiled into an <code>.apk</code> file as-is, and the original filename is preserved. You can navigate this
+ directory in the same way as a typical file system using URIs and read files as a stream of
+ bytes using the the {@link android.content.res.AssetManager}. For example, this is a good
+ location for textures and game data.</dd>
+
+ <dt><code>res/</code></dt>
+
+ <dd>
+ Contains application resources, such as drawable files, layout files, and string values. See
+ <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> for more
+ information.
+
+ <dl>
+ <dt><code>anim/</code></dt>
+
+ <dd>For XML files that are compiled into animation objects. See the <a href=
+ "{@docRoot}guide/topics/resources/animation-resource.html">Animation</a> resource
+ type.</dd>
+
+ <dt><code>color/</code></dt>
+
+ <dd>For XML files that describe colors. See the <a href=
+ "{@docRoot}guide/topics/resources/color-list-resource.html">Color Values</a> resource
+ type.</dd>
+
+ <dt><code>drawable/</code></dt>
+
+ <dd>For bitmap files (PNG, JPEG, or GIF), 9-Patch image files, and XML files that describe
+ Drawable shapes or a Drawable objects that contain multiple states (normal, pressed, or
+ focused). See the <a href=
+ "{@docRoot}guide/topics/resources/drawable-resource.html">Drawable</a> resource type.</dd>
+
+ <dt><code>layout/</code></dt>
+
+ <dd>XML files that are compiled into screen layouts (or part of a screen). See the <a href=
+ "{@docRoot}guide/topics/resources/layout-resource.html">Layout</a> resource type.</dd>
+
+ <dt><code>menu/</code></dt>
+
+ <dd>For XML files that define application menus.
+ See the <a href="{@docRoot}guide/topics/resources/menu-resource.html">Menus</a>
+ resource type.</dd>
+
+ <dt><code>raw/</code></dt>
+
+ <dd>For arbitrary raw asset files. Saving asset files here instead of in the
+ <code>assets/</code> directory only differs in the way that you access them. These files
+ are processed by aapt and must be referenced from the application using a resource
+ identifier in the {@code R} class. For example, this is a good place for media, such as MP3
+ or Ogg files.</dd>
+
+ <dt><code>values/</code></dt>
+
+ <dd>For XML files that are compiled into many kinds of resource. Unlike other resources in
+ the <code>res/</code> directory, resources written to XML files in this folder are not
+ referenced by the file name. Instead, the XML element type controls how the resources is
+ defined within them are placed into the {@code R} class.</dd>
+
+ <dt><code>xml/</code></dt>
+
+ <dd>For miscellaneous XML files that configure application components. For example, an XML
+ file that defines a {@link android.preference.PreferenceScreen}, {@link
+ android.appwidget.AppWidgetProviderInfo}, or <a href=
+ "{@docRoot}reference/android/app/SearchManager.html#SearchabilityMetadata">Searchability
+ Metadata</a>. See <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>
+ for more information about configuring these application components.</dd>
+ </dl>
+ </dd>
+
+ <dt><code>libs/</code></dt>
+
+ <dd>Contains private libraries.</dd>
+
+ <dt><code>AndroidManifest.xml</code></dt>
+
+ <dd>The control file that describes the nature of the application and each of its components.
+ For instance, it describes: certain qualities about the activities, services, intent receivers,
+ and content providers; what permissions are requested; what external libraries are needed; what
+ device features are required, what API Levels are supported or required; and others. See the
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>
+ documentation for more information</dd>
+
+ <dt><code>build.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>
+
+ <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>
+
+ <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>
+
+ <div class="sidebox-wrapper">
+ <div class="sidebox">
+ <h2>Library project example code</h2>
+
+ <p>The SDK includes an example application called <code>TicTacToeMain</code> 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>
+
+ <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>
+
+ <p>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 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>
+
+ <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> and run it on an Android device.
+ 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 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>
+
+ <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>Once you have added references to library projects to your Android project,
+ you can set their relative 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>
+
+ <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
+ in mind:</p>
+
+ <ul>
+ <li><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>
+ </li>
+
+ <li><p><strong>Use 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></li>
+
+ <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>
+ <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>
+
+ <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></li>
+
+ <li><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 in their manifest
+ files, in a <a href=
+ "{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></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>
+
+ <p>The tools do not support the use of raw asset files (saved in the <code>assets/</code> directory)
+ 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. However, resource files saved in the
+ <code>res/</code> directory are supported.</p></li>
+
+ <li><p><strong>Platform version must be lower than or equal to the Android 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 not 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></li>
+
+ <li> <p><strong>No restriction on library package names</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></li>
+
+ <li><p><strong>Each library project creates its own R class </strong></p>
+
+ <p>When you build the dependent application project, library projects are compiled and
+ merged with 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 main
+ project and the library project is created in all the packages that are needed including the main
+ project's package and the libraries' packages.</p></li>
+
+ <li><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. What is important is that the main
+ project can reference the library project through a relative link.</p></li>
+ </ul>
+
+
+ <h2 id="TestProjects">Test Projects</h2>
+
+ <p>Test projects contain Android applications that you write using the
+ <a href="{@docRoot}guide/topics/testing/index.html">Testing and
+ Instrumentation framework</a>. The framework is an extension of the JUnit test framework and adds
+ access to Android system objects. The file structure of a test project is the same as an
+ Android project.</p>
+
+ <dl>
+ <dt><code>src/</code></dt>
+
+ <dd>Includes your test source files. Test projects do not require an Activity <code>.java</code>
+ file, but can include one.</dd>
+
+ <dt><code>gen/</code></dt>
+
+ <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.</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">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 File</a>. Test
+ Projects have a special <a href=
+ "{@docRoot}guide/topics/manifest/instrumentation-element.html">
+ <code><instrumentation></code></a>
+ element that connects the test project with the application project.</dd>
+
+ <dt><code>build.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>
+
+ <dt><code>build.xml</code></dt>
+
+ <dd>The Ant build file for your project.</dd>
+
+ <dt><code>default.properties</code></dt>
+
+ <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.
+
+
+ <h2>Testing a library project</h2>
+
+ <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>
\ No newline at end of file
diff --git a/docs/html/guide/developing/projects/projects-cmdline.jd b/docs/html/guide/developing/projects/projects-cmdline.jd
new file mode 100644
index 0000000..de67b29
--- /dev/null
+++ b/docs/html/guide/developing/projects/projects-cmdline.jd
@@ -0,0 +1,285 @@
+page.title=Managing Projects on the Command Line
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#CreatingAProject">Creating an Android Project</a></li>
+
+ <li><a href="#UpdatingAProject">Updating a Project</a></li>
+
+ <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a></li>
+
+ <li><a href="#ReferencingLibraryProject">Referencing a Library Project from an
+ Application</a></li>
+ </ol>
+
+ <h2>See also</h2>
+
+ <ol>
+ <li><a href=
+ "{@docRoot}guide/developing/testing/testing_otheride.html#CreateTestProjectCommand">Testing
+ in Other IDEs</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>The <code>android</code> tool provides you with commands to create all three types of
+ projects. An Android project contains all of the files and resources that are needed to build a
+ project into an .apk file for installation.
+
+ <ul>
+ <li>An Android project contains all of the files and resources that are needed to build a project into
+ an .apk file for installation. You need to create an Android project for any application that you
+ want to eventually install on a device.</li>
+
+ <li>You can also designate an Android project as a library project, which allows it to be shared
+ with other projects that depend on it. Once an Android project is designated as a library
+ project, it cannot be installed onto a device.</li>
+
+ <li>Test projects extend JUnit test functionality to include Android specific functionality. For
+ more information on creating a test project, see <a href=
+ "{@docRoot}guide/developing/testing/testing_otheride.html">Testing in other IDEs</a>.</li>
+ </ul>
+
+
+ <h2 id="CreatingAProject">Creating an Android Project</h2>
+
+ <p>To create an Android project, you must use the <code>android</code> tool. When you create a
+ new project with <code>android</code>, it will generate a project directory with some default
+ application files, stub files, configuration files and a build file.</p>
+
+ <p>To create a new Android project, open a command-line, navigate to the <code>tools/</code>
+ directory of your SDK and run:</p>
+ <pre>
+android create project \
+--target <target_ID> \
+--name <your_project_name> \
+--path path/to/your/project \
+--activity <your_activity_name> \
+--package <your_package_namespace>
+</pre>
+
+ <ul>
+ <li><code>target</code> is the "build target" for your application. It corresponds to an
+ Android platform library (including any add-ons, such as Google APIs) that you would like to
+ build your project against. To see a list of available targets and their corresponding IDs,
+ execute: <code>android list targets</code>.</li>
+
+ <li><code>name</code> is the name for your project. This is optional. If provided, this name
+ will be used for your .apk filename when you build your application.</li>
+
+ <li><code>path</code> is the location of your project directory. If the directory does not
+ exist, it will be created for you.</li>
+
+ <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This
+ class file will be created for you inside
+ <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>
+ . This will also be used for your .apk filename unless you provide a <code>name</code>.</li>
+
+ <li><code>package</code> is the package namespace for your project, following the same rules as
+ for packages in the Java programming language.</li>
+ </ul>
+
+ <p>Here's an example:</p>
+ <pre>
+android create project \
+--target 1 \
+--name MyAndroidApp \
+--path ./MyAndroidAppProject \
+--activity MyAndroidAppActivity \
+--package com.example.myandroid
+</pre>
+
+ <p>Once you've created your project, you're ready to begin development. You can move your project
+ folder wherever you want for development, but keep in mind that you must use the <a href=
+ "{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) — located in the
+ SDK <code>platform-tools/</code> directory — to send your application to the emulator (discussed
+ later). So you need access between your project solution and the <code>platform-tools/</code> folder.</p>
+
+ <p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the <code>tools/</code> directory
+ 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>
+
+ <h2 id="UpdatingAProject">Updating a project</h2>
+
+ <p>If you're upgrading a project from an older version of the Android SDK or want to create a new
+ project from existing code, use the <code>android update project</code> command to update the
+ project to the new development environment. You can also use this command to revise the build
+ target of an existing project (with the <code>--target</code> option) and the project name (with
+ the <code>--name</code> option). The <code>android</code> tool will generate any files and
+ folders (listed in the previous section) that are either missing or need to be updated, as needed
+ for the Android project.</p>
+
+ <p>To update an existing Android project, open a command-line and navigate to the
+ <code>tools/</code> directory of your SDK. Now run:</p>
+ <pre>
+android update project --name <project_name> --target <target_ID>
+--path <path_to_your_project>
+</pre>
+
+ <ul>
+ <li><code>target</code> is the "build target" for your application. It corresponds to an
+ Android platform library (including any add-ons, such as Google APIs) that you would like to
+ build your project against. To see a list of available targets and their corresponding IDs,
+ execute: <code>android list targets</code>.</li>
+
+ <li><code>path</code> is the location of your project directory.</li>
+
+ <li><code>name</code> is the name for the project. This is optional—if you're not
+ changing the project name, you don't need this.</li>
+ </ul>
+
+ <p>Here's an example:</p>
+ <pre>
+android update project --name MyApp --target 2 --path ./MyAppProject
+</pre>
+
+ <h2 id="SettingUpLibraryProject">Setting up a library project</h2>
+
+ <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>
+
+ <p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory and
+ use this command:</p>
+ <pre class="no-pretty-print">
+android create lib-project --name <your_project_name> \
+--target <target_ID> \
+--path path/to/your/project \
+--package <your_library_package_namespace>
+</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">
+android.library=true
+</pre>
+
+ <p>Once the command completes, the library project is created and you can begin moving source
+ code and resources into it, as described in the sections below.</p>
+
+ <p>If you want to convert an existing application project to a library project, so that other
+ applications can use it, you can do so by adding a the <code>android.library=true</code> property
+ to the application's <code>default.properties</code> file.</p>
+
+ <h4>Creating the manifest file</h4>
+
+ <p>A library project's manifest file must declare all of the shared components that it includes,
+ just as would a standard Android application. For more information, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
+ project declares the Activity <code>GameActivity</code>:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <h4>Updating a library project</h4>
+
+ <p>If you want to update the build properties (build target, location) of the library project,
+ use this command:</p>
+ <pre>
+android update lib-project \
+--target <em><target_ID></em> \
+--path <em>path/to/your/project</em>
+</pre>
+
+ <h2 id="ReferencingLibraryProject">Referencing a Library Project</h2>
+
+ <p>If you are developing an application and want to include the shared code or resources from a
+ library project, you can do so easily by adding a reference to the library project in the
+ application project's build properties.</p>
+
+ <p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code>
+ directory and use this command:</p>
+ <pre>
+android update lib-project \
+--target <em><target_ID></em> \
+--path <em>path/to/your/project</em>
+--library <em>path/to/library_projectA</em>
+</pre>
+
+ <p>This command updates the application project's build properties to include a reference to the
+ library project. Specifically, it adds an <code>android.library.reference.<em>n</em></code>
+ property to the project's <code>default.properties</code> file. For example:</p>
+ <pre class="no-pretty-print">
+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">
+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">
+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>
+
+ <h3>Declaring library components in the the manifest file</h3>
+
+ <p>In the manifest file of the application project, you must add declarations of all components
+ that the application will use that are imported from a library project. For example, you must
+ declare any <code><activity></code>, <code><service></code>,
+ <code><receiver></code>, <code><provider></code>, and so on, as well as
+ <code><permission></code>, <code><uses-library></code>, and similar elements.</p>
+
+ <p>Declarations should reference the library components by their fully-qualified package names,
+ where appropriate.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
+ application declares the library Activity <code>GameActivity</code> like this:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="com.example.android.tictactoe.library.GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <p>For more information about the manifest file, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <h3 id="depAppBuild">Building a dependent application</h3>
+
+ <p>To build an application project that depends on one or more library projects, you can use the
+ standard Ant build commands and compile modes, as described in <a href=
+ "{@docRoot}guide/developing/building/index.html">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>
+
diff --git a/docs/html/guide/developing/projects/projects-eclipse.jd b/docs/html/guide/developing/projects/projects-eclipse.jd
new file mode 100644
index 0000000..45111f3
--- /dev/null
+++ b/docs/html/guide/developing/projects/projects-eclipse.jd
@@ -0,0 +1,235 @@
+page.title=Managing Projects in Eclipse
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#CreatingAProject">Creating an Android Project</a></li>
+
+ <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a></li>
+
+ <li><a href="#ReferencingLibraryProject">Referencing a Library Project</a></li>
+ </ol>
+
+ <h2>See also</h2>
+
+ <ol>
+ <li><a href=
+ "{@docRoot}guide/developing/testing/testing_eclipse.html#CreateTestProjectEclipse">Testing
+ in Eclipse, with ADT</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects
+ (Android project, Library project, and Test project):
+
+ <ul>
+ <li>An Android project contains all of the files and resources that are needed to build a project into
+ an .apk file for installation. You need to create an Android project for any application that you
+ want to eventually install on a device.</li>
+
+ <li>You can also designate an Android project as a library project, which allows it to be shared
+ with other projects that depend on it. Once an Android project is designated as a library
+ project, it cannot be installed onto a device.</li>
+
+ <li>Test projects extend JUnit test functionality to include Android specific functionality. For
+ more information on creating a test project, see <a href=
+ "{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse</a></li>
+ </ul>
+
+ <h2 id="CreatingAProject">Creating an Android Project</h2>
+
+ <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new Android
+ project (or a project from existing code). To create a new project:</p>
+
+ <ol>
+ <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li>
+
+ <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and click
+ <strong>Next</strong>.</li>
+
+ <li>Select the contents for the project:
+
+ <ul>
+ <li>Enter a <em>Project Name</em>. This will be the name of the folder where your project
+ is created.</li>
+
+ <li>Under Contents, select <strong>Create new project in workspace</strong>. Select your
+ project workspace location.</li>
+
+ <li>Under Target, select an Android target to be used as the project's Build Target. The
+ Build Target specifies which Android platform you'd like your application built against.
+
+ <p>Select the lowest platform with which your application is compatible.</p>
+
+ <p class="note"><strong>Note:</strong> You can change your the Build Target for your
+ project at any time: Right-click the project in the Package Explorer, select
+ <strong>Properties</strong>, select <strong>Android</strong> and then check the desired
+ Project Target.</p>
+ </li>
+
+ <li>Under Properties, fill in all necessary fields.
+
+ <ul>
+ <li>Enter an <em>Application name</em>. This is the human-readable title for your
+ application — the name that will appear on the Android device.</li>
+
+ <li>Enter a <em>Package name</em>. This is the package namespace (following the same
+ rules as for packages in the Java programming language) where all your source code will
+ reside.</li>
+
+ <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
+ for your main Activity class.</li>
+
+ <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates the minimum API
+ Level required to properly run your application. Entering this here automatically sets
+ the <code>minSdkVersion</code> attribute in the <a href=
+ "{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> of your
+ Android Manifest file. If you're unsure of the appropriate <a href=
+ "{@docRoot}guide/appendix/api-levels.html">API Level</a> to use, copy the API Level
+ listed for the Build Target you selected in the Target tab.</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+
+ <li>Click <strong>Finish</strong>.</li>
+ </ol>
+
+ <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard from the
+ <em>New</em> icon in the toolbar.</p>
+
+ <h2 id="SettingUpLibraryProject">Setting up a Library Project</h2>
+
+ <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.</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 figure 1.</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 <em>Properties</em> 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">
+
+ <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an
+ Android library project.</p>
+
+ <h3>Creating the manifest file</h3>
+
+ <p>A library project's manifest file must declare all of the shared components that it includes,
+ just as would a standard Android application. For more information, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
+ project declares the Activity <code>GameActivity</code>:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <h2 id="ReferencingLibraryProject">Referencing a library project</h2>
+
+ <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>Figure 2 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">
+
+ <p class="img-caption"><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>
+
+ <h3>Declaring library components in the the manifest file</h3>
+
+ <p>In the manifest file of the application project, you must add declarations of all components
+ that the application will use that are imported from a library project. For example, you must
+ declare any <code><activity></code>, <code><service></code>,
+ <code><receiver></code>, <code><provider></code>, and so on, as well as
+ <code><permission></code>, <code><uses-library></code>, and similar elements.</p>
+
+ <p>Declarations should reference the library components by their fully-qualified package names,
+ where appropriate.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
+ application declares the library Activity <code>GameActivity</code> like this:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="com.example.android.tictactoe.library.GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <p>For more information about the manifest file, see the documentation for <a href=
+ "{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+
+
+
+
+
+