使用库项目开发

库项目示例代码

SDK中包含了一个叫做TicTacToeMain 的样例应用程序，它展示了相关的应用如何使用Android库项目的代码和资源。TicTacToeMain应用使用了TicTacToeLib例子库项目的代码和资源。

要下载样例应用并在您的开发环境作为项目运行它们，使用Android SDK andAVD Manager下载Samples for SDKAPI 8组件到您的SDK中。

更多信息及浏览样例源代码，参阅TicTacToeMain application。

Android库项目是一个开发项目，拥有共享的Android源代码和资源。其它的Android应用项目能够引用库项目，而且在构建时能将其源代码编译到.apk文件中。多个应用项目能够引用相同的库项目，并且任何单个应用项目能够引用多个库项目。

如果你有在多个项目中通用的源代码和资源，你可以将它们移到一个库项目中，这样更容易在多个应用和版本中进行维护。下面是一些使用库项目的常见场景：

• 如果您正在开发多个相关的应用，它们使用了一些相同的组件，你应该从各自的应用项目中移除这些冗余的组件，并在库项目中创建单独的、可重复使用的组件集。
• 如果您正在创建的应用程序有免费和付费版本，你应该将这两个版本的通用部分移到一个库项目。使用不同包名的两个相关项目都将引用库项目，并仅提供两个应用版本之间差异的部分。

从结构上来讲，一个库项目和标准的Android应用项目差不多。例如，在项目根目录中包含了清单文件，与src/, res/一样类似的目录。库项目能够包含与标准Android项目相同类型的源代码和资源，并用相同的方式存储。例如，库项目的源代码能够通过它的R类来访问自身的资源。

然而，库项目与标准的Android应用项目的不同点在于您不能将其直接编译为.apk文件或在Android平台运行它们。同样，您不能像真正的库那样将库项目导出为自包含的JAR文件。相反，你必须间接编译相关应用的构建路径中所引用的库，然后构建应用。

当您依赖一个库项目来构建应用时，SDK工具编译这些库，并将其源代码合并到主项目中，然后再生成.apk文件。一个资源ID同时在应用和库中被定义，工具确保在应用中声明的资源获得优先权，不会将库项目中的资源编译到应用的.apk文件。这给了应用程序灵活性，是使用还是重新定义任何库中任何资源的行为或值。

要进一步组织代码，您的应用可以增加多个库项目的引用，然后指定每个库中资源的相对优先级。这让您采用累积的方式，在应用中建立起实际使用的资源。当一个应用引用定义了相同资源ID的两个库，这些工具会从库中选择较高优先级的资源，并放弃另一个。

一旦您加入了引用，这些工具会让您编辑应用项目的构建参数来设置它们的相对优先级。在构建时，这些工具按照优先级从低到高，将库一个一个地与应用合并。

请注意，库项目本身不能引用其它库项目，并且在构建时，在没有和应用合并之前，库项目之间不能彼此合并。不过，请注意，库项目能够使用正常的方式来导入一个外部库(JAR)。

下面的章节将描述如何使用ADT来建立和管理您的项目库。一旦您建立了库项目，并向它们移入了源代码，您就能够使用正常的方式向应用导入库的类和资源。

 

开发需求

Android库项目是一个构建时结构，因此，您能利用它们构建基于任何API级别的最终应用.apk，并能与Android库的任何版本一起编译。

不过，要使用库项目，您需要将开发环境升级到最新的工具和平台，因为老版本的工具和平台不支持库项目构建。具体来说，就是你需要下载和安装下列版本。

表格1.开发库项目所需基于的SDK工具和平台的最低版本。

组件	最低版本
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)

您能够使用Android SDK andAVD Manager来下载这些工具和平台，详细说明见Adding SDKComponents。

 

建立一个新的库项目

库项目是一个标准的Android工程，因此，你可以像创建新应用一样创建一个库项目。具体来说，你能够使用android工具来生成新的库项目所必要的文件和目录。

 

创建库项目

要创建一个新的库项目，定位到SDK下的<sdk>/tools/目录，并运行命令：

android create lib-project --name <your_project_name>

--target <target_ID>

--path path/to/your/project

--package <your_library_package_namespace>

create lib-project命令创建一个标准的项目结构，其中包含了向构建系统指明为库项目的预置属性。这通过在项目文件default.properties中增加此行来实现：

android.library=true

一旦命令完成，就建立了库项目，然后您可以将源代码和资源移到项目中，这在下面的章节中介绍。

如果您想将现有的应用项目转换为库项目，以让其它的应用来使用它，您可以通过向应用文件default.properties中加入android.library=true属性来实现。

 

创建清单文件

就像标准的Android应用一样，库项目的清单文件必须声明其所包含的所有共享组件。更多信息，请阅读AndroidManifest.xml。

例如，库项目例子TicTacToeLib声明了Activity——GameActivity：

<manifest>
  ...
  <application>
    ...
    <activity android:name="GameActivity" />
    ...
  </application>
</manifest>

 

更新库项目

如果您要更新库项目的构建属性（构建目标、位置），使用下面的命令：

android update lib-project 
--target <target_ID> 
--path path/to/your/project

 

从应用中引用库项目

如果您正在开发一个应用，想包含库项目中的共享代码或资源，您只要简单地在应用项目的构建属性中加入库项目引用即可。

要加入库项目引用，定位到SDK下的<sdk>/tools/目录，并运行命令：

android update lib-project 
--target <target_ID> 
--path path/to/your/project
--library path/to/library_projectA

这个命名更新应用项目的构建属性，使之包含库项目引用。具体来说，它向项目文件default.properties中，增加了一个android.library.reference.n属性。例如：

android.library.reference.1=path/to/library_projectA

如果你加入了多个库引用，要注意，您能够手工设置他们的相对优先级（和合并顺序），这通过编辑default.properties文件，将每个引用的.n索引调整适当。例如，假设有这些引用：

android.library.reference.1=path/to/library_projectA

android.library.reference.2=path/to/library_projectB

android.library.reference.3=path/to/library_projectC

您能使用下面的方法，将library_projectC设置为最高优先级：

android.library.reference.2=path/to/library_projectA

android.library.reference.3=path/to/library_projectB

android.library.reference.1=path/to/library_projectC

注意，引用的.n索引必须从1开始，而且要连续递增不能“留空”（不能跳过）。留空索引后面的引用将被忽略。

在构建时，应用每次合并一个库，优先级从低到高。注意，库自身不能引用其它的库，并且在构建时，库在与应用合并之前不能互相合并。

 

在清单文件中声明库组件

在应用项目的清单文件中，你必须加入应用使用、从库项目输出的所有组件的声明。例如，你必须声明全部的<activity>，<service>，<receiver>，<provider>等等，及<permission>，<uses-library>，和类似的元素。

必须通过它们的包全名来声明引用的库组件。

例如，库项目例子TicTacToeLib声明了Activity——GameActivity，像这样：

<manifest>
  ...
  <application>
    ...
    <activityandroid:name="com.example.android.tictactoe.library.GameActivity" />
    ...
  </application>
</manifest>

关于清单文件的更多信息，请参阅文档AndroidManifest.xml。

 

构建关联应用

要构建依赖一个或多个库项目的应用工程，你可以使用标准的Ant构建命令和编译模式，详见本文的构建应用一节。这个工具编译和合并应用中所引用的全部库，并将其作为编译关联应用工程的一部分。而不需要额外的命令或步骤。

 

开发建议

当您开发库项目和相关应用时，请要记住以下几点：

资源冲突

既然工具能够合并库项目及其关联应用的资源，那么，指定的资源ID就能在两个项目中被定义。在这种情况下，工具将会从应用，或库中选择最高优先级的资源，而丢弃其它资源。当您开发应用时，要知道，通用的资源ID可能会在多个项目中定义，并且会与来自应用或获取优先权的最高优先级库的资源合并。

使用前缀避免资源冲突

要避免通用资源ID的资源冲突，可以考虑使用一个其它前缀或其它对于一致的命名方案，该命名方案对于项目来说是独一无二的（或在所有项目中独一无二）。

库项目无法输出JAR

库不能发布二进制文件（例如jar文件）。这是因为主项目需要使用正确的资源ID来编译库项目。

库项目包含JAR库

您能开发一个自身包含JAR库的库项目。当您构建关联的应用项目时，工具在应用的.apk中自动定位并包含库。

库项目能够依赖外部JAR库

您能够开发一个依赖外部库（例如，地图外部库）的库项目。在这种情况下，相关的应用必须构建与外部库一致的目标（例如，GOOGLE的API插件）。也要注意，库项目和相关应用都必须在它们的清单文件的<uses-library元素中声明外部库。

库项目不能包含原始asset

工具不支持在库项目中使用原始asset文件。应用所使用的任何asset资源必须保存在应用项目自身的assets/目录下。

库项目和应用项目应用了不同的Adnroid平台版本

库会被编译为关联应用项目的一部分，因此，库项目所使用的API必须与编译应用项目所使用的Android库版本兼容。通常，库项目应该与应用所使用的API 级别相同或低一些。如果库项目使用的API级别比应用高，应用项目将会编译失败。例如，使用Android 1.5 API（API级别为3）的库就能够被完全接受的，它能用于Android 1.6（API级别为4）或Android 2.1（API级别为7）的项目。

库包的名称没有限制

库的包名字与使用该库的应用名字没有一致性的要求。

应用项目的gen/ folder中的多个R类

当您构建关联应用项目时，所有库的代码都被编译，并且合并到应用项目。每个库都有自己的R类，其名称遵循库的包名字。从主项目和库中所生成的R类，被创建在所有包含主项目包和库包的包中。

测试库项目

测试库项目中的代码和资源有两种推荐的方法：

• 您可以建立一个test project，来测试依赖库项目的应用项目。然后，您可以添加针对该库特定功能的测试到该项目中。
• 您可以建立一个依赖于库的标准应用项目，并加入测试工具。这能够让您建立自包含项目，同时包含了用于测试的测试/测试工具和代码。

 

库项目的存储位置

库项目的存储位置是没有明确的要求，对于关联的应用项目，只要应用项目能够通过相对链接引用到库项目即可。放置库项目最重要的是，主项目能够通过相对链接引用到库项目。

为应用连接调试器

本节描述如何在屏幕上（如CPU利用率）显示调试信息，及如何将您的IDE与模拟器上调试运行的应用连接起来。

使用Eclispse插件会自动连接一个调试器，但是您可以配置其它的IDE监听调试端口来接收调试信息。

1.     启动Dalvik DebugMonitor Server (DDMS)工具， 它充当IDE和模拟器之间的端口转发服务。

2.     在模拟器上设置可选的调试配置，如阻止应用程序的启动活动，直到连接了调试器。请注意，很多调试选项没有DDMS也可使用，如在模拟器上显示的CPU使用率或屏幕刷新率。

3.     配置IDE连接到8700端口来调试。阅读Configuring YourIDE to Attach to the Debugging Port。