Getting Started with Android Library Projects, Part 1

Android library projects provide reusable code and resources that can save you time and effort when developing apps — you don’t have to keep “reinventing the wheel.” This article is the first in a three-part series that introduces you to Android library projects. In Part 1, you learn about library project fundamentals.

Android Library Project Fundamentals

An Android library project is a container of shareable Android source code and resources that can be referenced from Android app projects. A library project is merged into an Android PacKage (APK) file (with file extension .apk) when an app project is built. Multiple app projects can reference the same library project. Any single app project can reference multiple library projects.

An Android library project is similar to an Android app project in that it also includes a project manifest file in the project’s root directory. Also, this directory contains src, res, and other directories that you also find when building an app project. Furthermore, the project can contain the same kinds of source code and resources as found in an app project.

However, there is a significant difference. You cannot compile a library project into an APK file because a library project doesn’t describe an app. Instead, it provides reusable code and resources that contribute to an app when the app’s project and source code refer to the library project. At build time, this code and these resources are merged into the app’s APK file.

When building an app that depends on a library project, the library is first compiled into a temporary JAR file that’s subsequently merged with the app project’s code and resources. If the same resource ID is defined in the app and in the library, the SDK ensures that the app’s resource gets priority; the library project’s resource isn’t compiled into the APK file.

An app project can add references to multiple library projects and specify their relative priorities. When multiple libraries that are referenced from the app define the same resource ID, the SDK selects the resource from the library with the higher priority and discards the other resource. The libraries are merged with the app one library at a time, starting from the lowest priority and progressing to the highest priority.

There are several items to remember when developing an Android library project and its dependent apps:

• Use prefixes to avoid resource conflicts. For example, to guarantee uniqueness, I would reverse my domain name and define @+id/ca_tutortutor_gameboard instead of @+id/gameboard in a library project resource file.

• You cannot export a library project to a JAR file. This capability will be introduced in a future release of the SDK tools.

• A library project can include a JAR library. You must manually edit the dependent app project’s build path and add a path to the JAR file.

• A library project can depend on an external JAR library. The dependent app project must build against a target that includes the external library. Also, the library and dependent app projects must declare the external library in their manifest files, in a <uses-library> element.

• Library projects cannot include raw assets. Raw asset files (saved in a library project’s assets directory) are ignored. Any asset resources used by an app must be stored in its project’s assets directory.

• The library project platform version number must be less than or equal to the app project platform version number. The API level (such as 10, which matches Android 2.3.3) used by a library project should be the same as or lower than the API level used by the dependent app.

• There is no restriction on library package names. A library’s package name isn’t required to match the package names of its dependent apps.

• Each library project creates its own R class. Each library has its own R class, named according to the library’s package name. The R class generated from the app project and its library project(s) is created in all the packages that are needed including the app project’s package and the library package(s).

• A library project’s storage location is flexible. Library projects can be stored anywhere on the hard drive as long as dependent app projects can reference them (via relative links).

Android library projects are created via the Android SDK in a similar manner to how Android app projects are created. The following command line syntax (split across multiple lines for readability) abstracts what you need to specify to create a library project:

android create lib-project --target target_ID
                           --path /path/to/project/project_name 
                           --package library_package_namespace

The create lib-project command is similar to create project (for creating an app project), but also adds the following line to the project’s project.properties file to indicate that the project is a library:

android.library=true

To reference the library from a dependent app project, first create the app project (via android create project, for example). Then execute an update command based on the following abstract syntax (split across multiple lines for readability) to reference the library project:

android update project --target target_ID 
                       --path /path/to/project/project_name 
                       --library relative/path/to/library/project

The update project command updates the app project to reference the library project by adding the following line to the app project’s project.properties file:

android.library.reference.n=library_project_relative_path

Conclusion

Now that you’ve learned the fundamentals of Android library projects, you’re ready to study an example. In the second part of this series, I present an about dialog box library project. Storing reusable about dialog boxes and other user interface items (such as custom widgets) in libraries helps to reduce app development time.