| page.title=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> |
| <ol> |
| <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> |
| |
| <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 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> |
| |
| <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="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>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 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 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> |
| |
| <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> |