524 lines
24 KiB
Plaintext
524 lines
24 KiB
Plaintext
page.title=Managing Projects Overview
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
<h2>In this document</h2>
|
|
|
|
<ol>
|
|
<li><a href="#ProjectFiles">Android Project Files</a></li>
|
|
<li><a href="#ApplicationModules">Android Application Modules</a></li>
|
|
|
|
<li><a href="#LibraryModules">Library Modules</a>
|
|
<ol>
|
|
<li><a href="#considerations">Development considerations</a></li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li><a href="#TestModules">Test Modules</a></li>
|
|
|
|
<li><a href="#testing">Testing a Library Module</a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
<p>An Android <em>project</em> contains everything that defines your Android app, from app
|
|
source code to build configurations and test code. The SDK tools require that your projects
|
|
follow a specific structure so it can compile and package your application correctly.
|
|
If you're using Android Studio, it takes care of all this for you.</p>
|
|
|
|
<p>A <em>module</em> is the first level of containment within a project that encapsulates
|
|
specific types of source code files and resources. There are several types of modules
|
|
with a project:</p>
|
|
|
|
<dl>
|
|
|
|
<dt><strong>Android Application Modules</strong></dt>
|
|
|
|
<dd>An Android Application Module is the container for your application's source code, resource
|
|
files, and application level settings, such as the module-level build file, resource files, and
|
|
Android Manifest file. The application module contents are eventually
|
|
built into the <code>.apk</code> file that gets installed on a device.</dd>
|
|
|
|
<dt><strong>Test Modules</strong></dt>
|
|
|
|
<dd>These modules contain code to test your application projects and are built into
|
|
test applications that run on a device. By default, Android Studio creates the
|
|
<em>androidTest</em> module for inserting JUnit tests. </dd>
|
|
|
|
<dt><strong>Library Modules</strong></dt>
|
|
|
|
<dd>These modules 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 modules cannot be installed onto a device, however, they are
|
|
pulled into the <code>.apk</code> file at build time.</dd>
|
|
|
|
|
|
<dt><strong>App Engine Modules</strong></dt>
|
|
|
|
<dd>Android Studio lets you easily add a cloud backend to your application. A backend allows you
|
|
to implement functionality such as backing up user data to the cloud, serving content to client
|
|
apps, real-time interactions, sending push notifications through Google Cloud Messaging for
|
|
Android (GCM), and more. App Engine modules are App Engine java Servlet Module for backend
|
|
development, App Engine java Endpoints Module to convert server-side Java code annotations into
|
|
RESTful backend APIs, and App Engine Backend with Google Cloud Messaging to send push notifications
|
|
from your server to your Android devices. </dd>
|
|
|
|
</dl>
|
|
|
|
<p>When you use the Android development tools to create a new project and the module, 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 Android Studio or the {@code android} tool to
|
|
generate your module. As your application grows in complexity, you might require new kinds of
|
|
resources, directories, and files.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> Project folders and files apply across the entire Android
|
|
project and override similar module file settings.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="ProjectFiles">Android Project Files</h2>
|
|
|
|
<p>Android Studio project files and settings provide project-wide settings that apply across all
|
|
modules in the project. </p>
|
|
|
|
<dl>
|
|
<dt><code>.idea</code></dt>
|
|
|
|
<dd>Directory for IntelliJ IDEA settings.</dd>
|
|
|
|
|
|
<dt><code>app</code></dt>
|
|
|
|
<dd>Application module directories and files. </dd>
|
|
|
|
|
|
<dt><code>build</code></dt>
|
|
|
|
<dd>This directory stories the build output for all project modules.</dd>
|
|
|
|
|
|
<dt><code>gradle</code></dt>
|
|
|
|
<dd>Contains the gradler-wrapper files. </dd>
|
|
|
|
|
|
<dt><code>.gitignore</code></dt>
|
|
|
|
<dd>Specifies the untracked files that Git should ignore.</dd>
|
|
|
|
|
|
<dt><code>build.gradle</code></dt>
|
|
|
|
<dd>Customizable properties for the build system. You can edit this file to specify the default
|
|
build settings used by the application modules and also set the location of your keystore and key alias
|
|
so that the build tools can sign your application when building in release mode. This file is
|
|
integral to the project, so maintain it in a source revision control system. </dd>
|
|
|
|
<dt><code>gradle.properties</code></dt>
|
|
|
|
<dd>Project-wide Gradle settings.</dd>
|
|
|
|
|
|
<dt><code>gradlew</code></dt>
|
|
|
|
<dd>Gradle startup script for Unix.</dd>
|
|
|
|
|
|
<dt><code>gradlew.bat</code></dt>
|
|
|
|
<dd>Gradle startup script for Windows. </dd>
|
|
|
|
<dt><code>local.properties</code></dt>
|
|
|
|
<dd>Customizable computer-specific properties for the build system, such as the path to the SDK
|
|
installation. Because the content of the file is specific to the local installation of the SDK,
|
|
the <code>local.properties</code> should not be maintained in a source revision control system. </dd>
|
|
|
|
|
|
<dt><code><project>.iml</code></dt>
|
|
|
|
<dd>Module file created by the IntelliJ IDEA to store module information.</dd>
|
|
|
|
<dt><code>settings.gradle</code></dt>
|
|
|
|
<dd>Specifies the sub-projects to build.</dd>
|
|
|
|
</dl>
|
|
|
|
|
|
<h2 id="ApplicationModules">Android Application Modules</h2>
|
|
|
|
<p>Android Application Modules are the modules that eventually get built into the <code>.apk</code>
|
|
files based on your build settings. They contain things such as application source code and resource
|
|
files. Most code and resource files are generated for you by default, while others should be created if
|
|
required. The following directories and files comprise an Android application module:</p>
|
|
|
|
<dl>
|
|
|
|
<dt><code>build/</code></dt>
|
|
|
|
<dd>Contains build folders for the specified build variants. Stored in the main application module.</dd>
|
|
|
|
|
|
<dt><code>libs/</code></dt>
|
|
|
|
<dd>Contains private libraries. Stored in the main application module.</dd>
|
|
|
|
|
|
|
|
|
|
<dt><code>src/</code></dt>
|
|
|
|
<dd>Contains your stub Activity file, which is stored at
|
|
<code>src<em>/main/java/<namespace.applicationname>/ActivityName></em>.java</code>. All other source
|
|
code files (such as <code>.java</code> or <code>.aidl</code> files) go here as well.</dd>
|
|
|
|
<dl>
|
|
<dt><code>androidTest/</code></dt>
|
|
|
|
<dd>Contains the instrumentation tests. For more information, see the
|
|
<a href="{@docRoot}tools/testing/index.html">Android Test documentation</a>.</dd>
|
|
|
|
<dt><code>main/java/com.>project<.>app<</code></dt>
|
|
|
|
<dd>Contains Java code source for the app activities.</dd>
|
|
|
|
<dt><code>main/jni/</code></dt>
|
|
|
|
<dd>Contains native code using the Java Native Interface (JNI). For more information, see the
|
|
<a href="{@docRoot}tools/sdk/ndk/index.html">Android NDK documentation</a>.</dd>
|
|
|
|
<dt><code>main/gen/</code></dt>
|
|
|
|
<dd>Contains the Java files generated by Android Studio, such as your <code>R.java</code> file and
|
|
interfaces created from AIDL files.</dd>
|
|
|
|
<dt><code>main/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 {@link android.content.res.AssetManager}. For example, this is a good
|
|
location for textures and game data.</dd>
|
|
|
|
<dt><code>main/res/</code></dt>
|
|
|
|
<dd>Contains application resources, such as drawable files, layout files, and string values
|
|
in the following directories. 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 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 is essentially the same as
|
|
saving them in the <code>assets/</code> directory. The only difference is how 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 define resources by XML element type. 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
|
|
defined within the XML files 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>
|
|
|
|
<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>
|
|
|
|
</dl>
|
|
|
|
<dt><code>.gitignore/</code></dt>
|
|
|
|
<dd>Specifies the untracked files ignored by git.</dd>
|
|
|
|
<dt><code>app.iml/</code></dt>
|
|
|
|
<dd>IntelliJ IDEA module</dd>
|
|
|
|
<dt><code>build.gradle</code></dt>
|
|
|
|
<dd>Customizable properties for the build system. You can edit this file to override default
|
|
build settings used by the manifest file and also set the location of your keystore and key alias
|
|
so that the build tools can sign your application when building in release mode. This file is
|
|
integral to the project, so maintain it in a source revision control system. </dd>
|
|
|
|
<dt><code>proguard-rules.pro</code></dt>
|
|
|
|
<dd>ProGuard settings file. </dd>
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
<h2 id="LibraryModules">Library Module</h2>
|
|
|
|
<div class="sidebox-wrapper">
|
|
<div class="sidebox">
|
|
<h2>Library module 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 module. The TicTacToeMain
|
|
application uses code and resources from an example library module called TicTacToeLib.</p>
|
|
|
|
<p>To download the sample applications and run them as modules in
|
|
your environment, use the <em>Android SDK Manager</em> to download the "Samples for
|
|
SDK API 8" (or later) module 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 module</em> is a development module that holds shared Android
|
|
source code and resources. Other Android application modules can reference the library module
|
|
and, at build time, include its compiled sources in their <code>.apk</code> files. Multiple
|
|
application modules can reference the same library module and any single application module
|
|
can reference multiple library modules.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> You need SDK Tools r14 or newer to use the new library
|
|
module feature that generates each library module into its own JAR file.
|
|
You can download the tools and platforms using the
|
|
<em>Android SDK Manager</em>, as described in
|
|
<a href="{@docRoot}tools/help/sdk-manager.html">SDK tools help</a>.</p>
|
|
|
|
<p>If you have source code and resources that are common to multiple Android projects, you
|
|
can move them to a library module so that it is easier to maintain across applications and
|
|
versions. Here are some common scenarios in which you could make use of library modules:</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 module and create a
|
|
single, reusable set of the same components in a library module.</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 module. The two
|
|
dependent modules, with their different package names, will reference the library module
|
|
and provide only the difference between the two application versions.</li>
|
|
</ul>
|
|
|
|
<p>Structurally, a library module is similar to a standard Android application module. For
|
|
example, it includes a manifest file at the module root, as well as <code>src/</code>,
|
|
<code>res/</code> and similar directories. The module can contain the same types of source
|
|
code and resources as a standard Android module, stored in the same way. For example, source
|
|
code in the library module can access its own resources through its <code>R</code> class.</p>
|
|
|
|
<p>However, a library module differs from a standard Android application module 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 module 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 module, the SDK tools compile the
|
|
library into a temporary JAR file and use it in the main module, then uses the
|
|
result to generate the <code>.apk</code>. In cases where a resource ID is defined in both the
|
|
application and the library, the tools ensure that the resource declared in the application gets
|
|
priority and that the resource in the library module 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
|
|
modules, 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 modules to your Android application module,
|
|
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>Library modules can reference other library modules and can import an external library
|
|
(JAR) in the normal way.</p>
|
|
|
|
<h3 id="considerations">Development considerations</h3>
|
|
|
|
<p>As you develop your library modules 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 module with those of a dependent application
|
|
module, a given resource ID might be defined in both modules. 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 module (or is unique across all project modules).</p></li>
|
|
|
|
<li><p><strong>You cannot export a library module to a JAR file</strong></p>
|
|
|
|
<p>A library cannot be distributed as a binary file (such as a JAR file). This will be added in a
|
|
future version of the SDK Tools.</p></li>
|
|
|
|
<li><p><strong>A library module can include a JAR library</strong></p>
|
|
|
|
<p>You can develop a library module that itself includes a JAR library; however you need to
|
|
manually edit the dependent application modules's build path and add a path to the JAR file.</p></li>
|
|
|
|
<li><p><strong>A library module can depend on an external JAR library</strong></p>
|
|
|
|
<p>You can develop a library module 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 module 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 modules 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 module. Any asset resources
|
|
used by an application must be stored in the <code>assets/</code> directory of the application
|
|
module 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 module</strong></p>
|
|
|
|
<p>A library is compiled as part of the dependent application module, so the API used in the
|
|
library module must be compatible with the version of the Android library used to compile the
|
|
application module. In general, the library module should use an <a href=
|
|
"{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level</a> that is the same as — or lower
|
|
than — that used by the application. If the library module uses an API level that is
|
|
higher than that of the application, the application module 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) module, for instance.</p></li>
|
|
|
|
<li> <p><strong>No restriction on library module 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 module creates its own R class </strong></p>
|
|
|
|
<p>When you build the dependent application modules, library modules are compiled and
|
|
merged with the application module. 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
|
|
module and the library module is created in all the packages that are needed including the main
|
|
module's package and the libraries' packages.</p></li>
|
|
|
|
<li><p><strong>Library module storage location</strong></p>
|
|
|
|
<p>There are no specific requirements on where you should store a library module, relative to a
|
|
dependent application module, as long as the application module can reference the library
|
|
module by a relative link. What is important is that the main
|
|
module can reference the library module 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}tools/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. </p>
|
|
|
|
<p>The test projects are now automatically part of the app source folder. When a new application
|
|
module is created, Android Studio creates the <code>src/androidTest</code> source set. This
|
|
source set contains tests for the default configuration and is combined with the <em>debug</em>
|
|
build type to generate a test application. </p>
|
|
|
|
<img src="{@docRoot}images/tools/studio-androidtest-folder.png">
|
|
<p class="img-caption"><strong>Figure 1.</strong> androidTest Folder.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> The <code>src/androidTest</code> source set may not be
|
|
created for every type of available module template. If this source set is not created, you
|
|
can just create it for that module.</p>
|
|
|
|
<p>For each product flavor, create a test folder specific to that product flavor. </p>
|
|
|
|
<dl>
|
|
<dt><code>src/main/</code></dt>
|
|
<dd><code>src/androidTest/</code></dt>
|
|
|
|
<dt><code>src/productFlavor1/</code></dt>
|
|
<dd><code>src/testproductFlavor1/</code></dd>
|
|
|
|
<dt><code>src/productFlavor2/</code></dt>
|
|
<dd><code>src/testproductFlavor2/</code></dd>
|
|
|
|
</dl>
|
|
|
|
<p>The test manifests are always generated so a manifest in a test source set is optional.</p>
|
|
|
|
<p>The test applications run against the <em>debug</em> build type. This can be configured
|
|
using the <code>testBuildType</code> property in the build file.</p>
|
|
|
|
|
|
<p>For more information, see the
|
|
<a href="{@docRoot}tools/testing/index.html">Testing</a> section.</p>
|
|
|
|
|
|
<h2 id="testing">Testing a Library Module</h2>
|
|
|
|
<p>There are two recommended ways of setting up testing on code and resources in a library
|
|
module:</p>
|
|
|
|
<ul>
|
|
<li>You can set up a <a href="{@docRoot}tools/testing/testing_otheride.html">test
|
|
module</a> that instruments an application module that depends on the library module. You
|
|
can then add tests to the module for library-specific features.</li>
|
|
|
|
<li>You can set up a standard application module that depends on the library and put
|
|
the instrumentation in that module. This lets you create a self-contained module that
|
|
contains both the tests/instrumentations and the code to test.</li>
|
|
</ul>
|