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 android tool on the command line. There are three types of projects, and
+ they all share the same general structure but differ in function:
.apk file that you install on a
+ device..apk file at build time.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.
+ +Android projects are the projects that eventually get built into an .apk 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:
src/src/your/package/namespace/ActivityName.java. All other source code
+ files (such as .java or .aidl files) go here as well.bin.apk file and other
+ compiled resources.jnigen/R.java file and
+ interfaces created from AIDL files.assets/.apk 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.res/anim/color/drawable/layout/menu/raw/assets/ 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.values/res/ 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.xml/libs/AndroidManifest.xmlbuild.propertiesbuild.xmldefault.propertiesThe SDK includes an example application called TicTacToeMain 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.
To download the sample applications and run them as projects in + your environment, use the Android SDK and AVD Manager to download the "Samples for + SDK API 8" component into your SDK.
+ +For more information and to browse the code of the samples, see + the TicTacToeMain + application.
+An Android library project 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 .apk files. Multiple
+ application projects can reference the same library project and any single application project
+ can reference multiple library projects.
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:
+ +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 src/,
+ res/ 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 R class.
However, a library project differs from an standard Android application project in that you
+ cannot compile it directly to its own .apk 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.
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 .apk. 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 .apk.
+ This gives your application the flexibility to either use or redefine any resource behaviors or
+ values that are defined in any library.
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.
+ +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.
+ +Note that a library project cannot itself reference another library project and that, at + build time, library projects are not 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.
+ +Android library projects are a build-time construct, so you can use them to build a final
+ application .apk that targets any API level and is compiled against any version of
+ the Android library.
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:
+ +Table 1. Minimum versions of SDK tools and platforms on + which you can develop library projects.
+ +| Component | + +Minimum Version | +
|---|---|
| SDK Tools | + +r6 (or higher) | +
| Android 2.2 platform | + +r1 (or higher) | +
| Android 2.1 platform | + +r2 (or higher) | +
| Android 2.0.1 platform | + +not supported | +
| Android 2.0 platform | + +not supported | +
| Android 1.6 platform | + +r3 (or higher) | +
| Android 1.5 platform | + +r4 (or higher) | +
| ADT Plugin | + +0.9.7 (or higher) | +
You can download the tools and platforms using the Android SDK and AVD Manager, as + described in Adding SDK Components.
+ +As you develop your library project and dependent applications, keep the points listed below + in mind:
+ +Resource conflicts
+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.
+Use prefixes to avoid resource conflicts
+ +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).
You cannot export a library project to a JAR file
+ +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.
One library project cannot reference another
+ +A library cannot depend on another library
A library project can include a JAR library
+ +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.
A library project can depend on an external JAR library
+ +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 <uses-library>
+ element.
Library project cannot include AIDL files
+ +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.
Library projects cannot include raw assets
+ +The tools do not support the use of raw asset files (saved in the assets/ directory)
+ in a library project. Any asset resources
+ used by an application must be stored in the assets/ directory of the application
+ project itself. However, resource files saved in the
+ res/ directory are supported.
Platform version must be lower than or equal to the Android project
+ +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 API level 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.
No restriction on library package names
+ +There is no requirement for the package name of a library to be the same as that of + applications that use it.
Each library project creates its own R class
+ +When you build the dependent application project, library projects are compiled and
+ merged with the application project. Each library has its own R class, named according
+ to the library's package name. The R 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.
Library project storage location
+ +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.
Test projects contain Android applications that you write using the + Testing and + Instrumentation framework. 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.
+ +src/.java
+ file, but can include one.gen/R.java file and
+ interfaces created from AIDL files.assets/res/AndroidManifest.xml<instrumentation>
+ element that connects the test project with the application project.build.propertiesbuild.xmldefault.propertiesThere are two recommended ways of setting up testing on code and resources in a library + project:
+ +The android 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.
+
+
To create an Android project, you must use the android tool. When you create a
+ new project with android, it will generate a project directory with some default
+ application files, stub files, configuration files and a build file.
To create a new Android project, open a command-line, navigate to the tools/
+ directory of your SDK and run:
+android create project \ +--target <target_ID> \ +--name <your_project_name> \ +--path path/to/your/project \ +--activity <your_activity_name> \ +--package <your_package_namespace> ++ +
target 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: android list targets.name 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.path is the location of your project directory. If the directory does not
+ exist, it will be created for you.activity is the name for your default {@link android.app.Activity} class. This
+ class file will be created for you inside
+ <path_to_your_project>/src/<your_package_namespace_path>/
+ . This will also be used for your .apk filename unless you provide a name.package is the package namespace for your project, following the same rules as
+ for packages in the Java programming language.Here's an example:
++android create project \ +--target 1 \ +--name MyAndroidApp \ +--path ./MyAndroidAppProject \ +--activity MyAndroidAppActivity \ +--package com.example.myandroid ++ +
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 Android Debug Bridge (adb) — located in the
+ SDK platform-tools/ directory — to send your application to the emulator (discussed
+ later). So you need access between your project solution and the platform-tools/ folder.
Tip: Add the platform-tools/ as well as the tools/ directory
+ to your PATH environment variable.
Caution: 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.)
+ +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 android update project 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 --target option) and the project name (with
+ the --name option). The android 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.
To update an existing Android project, open a command-line and navigate to the
+ tools/ directory of your SDK. Now run:
+android update project --name <project_name> --target <target_ID> +--path <path_to_your_project> ++ +
target 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: android list targets.path is the location of your project directory.name is the name for the project. This is optional—if you're not
+ changing the project name, you don't need this.Here's an example:
++android update project --name MyApp --target 2 --path ./MyAppProject ++ +
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 android tool
+ to generate a new library project with all of the necessary files and folders.
To create a new library project, navigate to the <sdk>/tools/ directory and
+ use this command:
+android create lib-project --name <your_project_name> \ +--target <target_ID> \ +--path path/to/your/project \ +--package <your_library_package_namespace> ++ +
The create lib-project 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 default.properties file:
+android.library=true ++ +
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.
+ +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 android.library=true property
+ to the application's default.properties file.
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 + AndroidManifest.xml.
+ +For example, the TicTacToeLib example library
+ project declares the Activity GameActivity:
+<manifest> + ... + <application> + ... + <activity android:name="GameActivity" /> + ... + </application> +</manifest> ++ +
If you want to update the build properties (build target, location) of the library project, + use this command:
++android update lib-project \ +--target <target_ID> \ +--path path/to/your/project ++ +
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.
+ +To add a reference to a library project, navigate to the <sdk>/tools/
+ directory and use this command:
+android update lib-project \ +--target <target_ID> \ +--path path/to/your/project +--library path/to/library_projectA ++ +
This command updates the application project's build properties to include a reference to the
+ library project. Specifically, it adds an android.library.reference.n
+ property to the project's default.properties file. For example:
+android.library.reference.1=path/to/library_projectA ++ +
If you are adding references to multiple libraries, note that you can set their relative
+ priority (and merge order) by manually editing the default.properties file and
+ adjusting the each reference's .n index as appropriate. For example, assume
+ these references:
+android.library.reference.1=path/to/library_projectA +android.library.reference.2=path/to/library_projectB +android.library.reference.3=path/to/library_projectC ++ +
You can reorder the references to give highest priority to library_projectC in
+ this way:
+android.library.reference.2=path/to/library_projectA +android.library.reference.3=path/to/library_projectB +android.library.reference.1=path/to/library_projectC ++ +
Note that the .n index in the references must begin at "1" and increase
+ uniformly without "holes". References appearing in the index after a hole are ignored.
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.
+ +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 <activity>, <service>,
+ <receiver>, <provider>, and so on, as well as
+ <permission>, <uses-library>, and similar elements.
Declarations should reference the library components by their fully-qualified package names, + where appropriate.
+ +For example, the TicTacToeMain example
+ application declares the library Activity GameActivity like this:
+<manifest> + ... + <application> + ... + <activity android:name="com.example.android.tictactoe.library.GameActivity" /> + ... + </application> +</manifest> ++ +
For more information about the manifest file, see the documentation for + AndroidManifest.xml.
+ +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 Building Your Application, 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.
+ 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 0000000000000..45111f3c8383b --- /dev/null +++ b/docs/html/guide/developing/projects/projects-eclipse.jd @@ -0,0 +1,235 @@ +page.title=Managing Projects in Eclipse +@jd:body + +Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects + (Android project, Library project, and Test project): + +
The ADT plugin provides a New Project Wizard that you can use to quickly create a new Android + project (or a project from existing code). To create a new project:
+ +Select the lowest platform with which your application is compatible.
+ +Note: You can change your the Build Target for your + project at any time: Right-click the project in the Package Explorer, select + Properties, select Android and then check the desired + Project Target.
+minSdkVersion attribute in the <uses-sdk> of your
+ Android Manifest file. If you're unsure of the appropriate API Level to use, copy the API Level
+ listed for the Build Target you selected in the Target tab.Tip: You can also start the New Project Wizard from the + New icon in the toolbar.
+ +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.
+ +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.
+ +Next, set the project's properties to indicate that it is a library project:
+ +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.
+ +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.
+ +
+
+ Figure 1. Marking a project as an + Android library project.
+ +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 + AndroidManifest.xml.
+ +For example, the TicTacToeLib example library
+ project declares the Activity GameActivity:
+<manifest> + ... + <application> + ... + <activity android:name="GameActivity" /> + ... + </application> +</manifest> ++ +
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.
+ +To add a reference to a library project, follow these steps:
+ +As soon as the Properties dialog closes, Eclipse rebuilds the project, including the contents + of the library project.
+ +Figure 2 shows the Properties dialog that lets you add library references and move + them up and down in priority.
+
+ Figure 2. Adding a reference to a + library project in the properties of an application project.
+ +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 Up and + Down 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.
+ +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 <activity>, <service>,
+ <receiver>, <provider>, and so on, as well as
+ <permission>, <uses-library>, and similar elements.
Declarations should reference the library components by their fully-qualified package names, + where appropriate.
+ +For example, the TicTacToeMain example
+ application declares the library Activity GameActivity like this:
+<manifest> + ... + <application> + ... + <activity android:name="com.example.android.tictactoe.library.GameActivity" /> + ... + </application> +</manifest> ++ +
For more information about the manifest file, see the documentation for AndroidManifest.xml.
+ + + + + + +