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 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.
Before the Android 4.0 SDK (r14), Android library projects were regarded as extra source code and resource folders when compiling an app’s source code and resources. Because this arrangement proved to be extremely fragile in Eclipse, and because developers prefer to distribute libraries of compiled code and resources as JAR files, r14 introduced a compiled-code library mechanism for library projects. Check out Changes to Library Projects in Android SDK Tools, r14 for more information.The compiled-code library mechanism is the first step toward distributing libraries as JAR files. The nature of Android resources with their compiled IDs needs to be addressed before this JAR distribution capability is fully realized (in a future release of the Android tools).
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.
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.
Library projects can reference other library projects. Also, they can import external JAR-based libraries of compiled Java code that doesn’t reference Android APIs.
There are several items to remember when developing an Android library project and its dependent apps:
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).
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 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:
--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
You could also specify --name project_name when creating the library project. However, you can generally omit --name because the value assigned to this optional parameter isn’t used beyond being assigned to the <project> element’s name attribute in the project’s build.xml file.
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:
You could also specify --name project_name when creating the library project. However, you can generally omit --name because the value assigned to this optional parameter isn’t used beyond being assigned to the <project> element’s name attribute in the project’s build.xml file.
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
--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
A library project reference has the form android.library.reference.n, where n is an integer value starting at 1. Repeated invocations of the android update project command, where each command identifies a different library project, introduce additional library references to project.properties. The integer value increments by 1 (2, 3, 4, and so on) for each successive reference. Holes between numbers (1 and 3 are specified, but not 2, for example) are not allowed; references appearing after the hole are ignored (when 2 isn’t specified 3 would be ignored, for example).
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.
A library project reference has the form android.library.reference.n, where n is an integer value starting at 1. Repeated invocations of the android update project command, where each command identifies a different library project, introduce additional library references to project.properties. The integer value increments by 1 (2, 3, 4, and so on) for each successive reference. Holes between numbers (1 and 3 are specified, but not 2, for example) are not allowed; references appearing after the hole are ignored (when 2 isn’t specified 3 would be ignored, for example).
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.
No comments:
Post a Comment