diff options
author | Robert Ly <robertly@google.com> | 2010-12-22 11:05:10 -0800 |
---|---|---|
committer | Robert Ly <robertly@google.com> | 2010-12-23 13:03:41 -0800 |
commit | bf6c338c8f22d635ccbf63248c13d91d78862e53 (patch) | |
tree | 41b6fcb4e1b3a2c2e7e73a68f85e589238032c9c /docs/html | |
parent | 70119929549b6d241244c51952ed1f4a313a5ff7 (diff) | |
download | frameworks_base-bf6c338c8f22d635ccbf63248c13d91d78862e53.zip frameworks_base-bf6c338c8f22d635ccbf63248c13d91d78862e53.tar.gz frameworks_base-bf6c338c8f22d635ccbf63248c13d91d78862e53.tar.bz2 |
Doc change: adding Projects section of dev guide
Change-Id: I0f9a0fdd238027713bff00d4f6273e168b0dc050
Diffstat (limited to 'docs/html')
-rw-r--r-- | docs/html/guide/developing/projects/index.jd | 493 | ||||
-rw-r--r-- | docs/html/guide/developing/projects/projects-cmdline.jd | 285 | ||||
-rw-r--r-- | docs/html/guide/developing/projects/projects-eclipse.jd | 235 |
3 files changed, 1013 insertions, 0 deletions
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> + + + + + + + |