进入 Harmony 世界，第 5 部分: Harmony 基础设施介绍

文档选项 未显示需要 JavaScript 的文档选项

级别： 中级

邱 小侠 (qiuxiaoxia@gmail.com), 南京大学研究生, 南京大学研究生
沈 羽, 软件工程师, IBM　

2007 年 4 月 06 日

Apache Harmony 是 2005 年 5 月宣布的开放源码 Java SE 实现，本文是由 5 部分组成的 进入 Harmony 世界 系列文章的第五篇，这个系列主要介绍 Apache Harmony 项目的内部实现，最新发展现状和开源 Java 开发的模式，并鼓励和欢迎大家参与到 Harmony 的社区中来。

本文较详细地介绍了 Harmony 项目中一些重要的基础设施，展示如何搭建配置开发环境，以及如何参与到 Harmony 项目的实际开发中来。

什么是 Harmony

在 Java 开发社区中迫切的需要一个开源的 Java2 标准版（J2SE）运行平台（包括运行时环境和类库）。目前有很多基于这个目标的项目正在开发之中，比如 Kaffe，Classpath 等。同时，也有很多项目正在进行虚拟机的开发，比如 GCJ 和 IKVM。所有的这些工作，提供了一系列纷繁复杂的解决方案。然而正是多样性产生了障碍。比如 Kaffe 的类库不能在 GCJ 虚拟机上运行。这样的障碍降低了这些项目的价值。

Harmony 是 ASF（Apache Software Foundation）基金会资助的一个开源项目。该项目的目标是开发一个模块化的开源的 Java2 标准版（J2SE）运行时环境和类库。对于每一个新加入的项目，ASF 都要首先将其放入孵化箱，直到这个项目趋于稳定——使用的开发工具趋于稳定、开发的流程趋于稳定、关于开发的讨论趋于稳定、项目决议流程趋于稳定。处于孵化阶段的项目并不一定是代码不够完整，不够稳定，只是表示项目还没有完全被 ASF 基金会认可。Harmony 项目刚于近期完成了其孵化阶段，正式成为 Apache 的一个顶级项目，这意味着 Harmony 项目正在慢慢成熟。

Harmony 项目的设计目标有两个：

• 在 Apache Licence v2 的许可之下，独立的（不阅读 Sun JDK 的源代码，仅仅根据 Java SE 5 specification）开发一个与 Java SE 5 兼容的 JDK。
• 通过 Harmony 的开发社区，创建一个模块化的架构（包括虚拟机和类库）。该架构允许所有的独立开发项目可以共享运行时组件。

Harmony 项目的目标是能让不同厂商，开发小组，使用不同许可证的项目能够和谐共处。这也是 Harmony 这个名字的由来。

Harmony 主页

你可以通过以下链接访问Harmony 主页。主页上包含了和 Harmony 相关的信息，包括版权信息，新闻，最新下载等等。

点击 Community 下的 Mailing Lists 链接会给出 Harmony 讨论组的相关信息，Bug Tracker 链接会将用户带到 Harmony 项目使用的臭虫追踪系统 JIRA 中去。这两个系统在整个开发中具有重要作用，后文将会详细介绍

Harmony 开发环境

Harmony 项目推荐使用的开发环境是 Elicpse version 3.2 integration build I20060119 或者之后的版本。Eclipse 可以从其官方首页下载。在 Eclipse 下进行 Harmony 的开发还需要下载其他的一些组件，包括 Subversion 客户端 Subclipse（Eclipse 插件）；类库的最新构建版本，用户可以直接下载编译好的类库包，也可以下载源文件自己编译；一个支持 Harmony 类库的虚拟机，需要同类库放置在一起，需要注意的是，IBM 公司为 Harmony 社区贡献了一个虚拟机实现（不含源码），它是基于 IBM 的 J9 虚拟机实现的基础之上的。

下面将给出配置开发环境的步骤，在这之前先定义配置中将会用到的一些符号：

• ${ECLIPSE_HOME}：Eclipse 的安装目录。
• ${HARMONY_HOME}：Harmony 类库源码的根路径，从 svn 上检出 trunk 目录即是。
• ${MODULE}：代表 ${HARMONY_HOME}/module 下的任一子目录

首先将 VM plugin 拷贝到 ${ECLIPSE_HOME}/plugins 目录下。由于 Harmony 的类库是模块化设计的，因此必须通过这个插件使得 Eclipse 认出 Harmony 的 JRE 环境。

接着下载最新的 snapshot 和 VM，将这两个压缩文件解压到相同的目录下。这两个压缩包中的目录结构不需要作改动，解压到相同的目录下就能够形成一个完整的运行时环境——虚拟机加类库。解压之后的目录结构如图4所示

然后打开 Eclipse，选择 Help 菜单，Software Updates 子菜单，Find and Install 选项。图5 显示选择 Find and Install 选项。

在接下来的 Install 面板上选择 New Remote Site。图6 显示添加 Subclipse 的远程站点。点击 OK，Eclipse 将自动安装 subclipse。

在安装完成 Subclipse 之后，选择 Windows 菜单，Open Perspective 选项，选择 Other。图7 显示，Select Perspective 面板中，新增加了一种视图　SVN 资料库研究，选择这种视图。

Eclipse 将转到该视图。在 SVN 资源库选项卡中点击鼠标右键，选择新建，接着选择资源库位置。在弹出的对话框中输入需要添加的资源库位置。

然后鼠标右键点击 Harmony 项目，或者 Harmony 项目下的某个包。如选择 text 包。选择取出为。图9 显示将 Harmony 项目下的 text 包导出至本地工作目录之中。图9 将 text 包导出至本地工作目录之中。

项目的源代码导出之后就需要对 Eclipse 进行配置，选择 Window 菜单，Preferences 选项。在弹出的面板中选择 Java->Compiler->Building，将 Circular dependencies 设置为 Warning，消除 circular dependency 即发生循环依赖时带来的问题。

之后选择 Plug-in Development，点击 Compilers 子选项。图11显示，将 Unresolved dependencies 选项设置为 warning。

点击 Target Platform，图12 显示在 Location 输入框中，输入 ${HARMONY_HOME}\deploy\jdk\jre\lib\boot。虽然类库可以按功能划分模块，但这种划分内部耦合是很严重的，彼此依赖。当以当个模块作为项目导入到 Eclipse 进行开发的时候，由于依赖缺失，会导致构建失败。这样统一设置后，Eclipse 就会自动导入各个模块编译好的Jar包，更方便的解决模块间的依赖问题。

构建部署类库

SVN 资源库结构

Harmony 的 Subversion（SVN） 服务器的资源库被分成了几个部分，其中最主要的两个部分分别是“标准”（standard）和“加强”（enhanced）。“标准”部分遵照标准的 Apache 式开发流程，只要开发者签署通过了 Apache 官方的 ICLA（Individual Contributor License Agreement ） 协议，就可以在上面贡献代码，Harmony 的网站内容、文档和其他一些相关文件就在这个部分下进行管理。而“加强”部分还要求提交者（committer）必须是经过授权的贡献者（Authorized Contributor）。因为最为重要的源码就在这个部分，所以对其有更严格的管理要求，这也是为了防止开发者上传补丁时，对源码有意或无意的破坏，降低代码维护的风险。其总体结构如图13所示：

类库结构

由于类库开发的特殊性，整个源码结构被分解为许多模块，这样有助于开源项目的开发，使得代码间可以不依赖共享的运行组件，同时也使得对单独组件的修改不至于影响到其他组件，分散风险，让所有的开发者能并行开发各个不同组件。当开发者按照前面的步骤从 Harmony 主页上检出类库的源码后，开发者会看到其目录结构如下：

• make 存放实际完成类库构建的 ANT 脚本文件，trunk 目录下的 build.xml 脚本所提供的各个目标会调用这些实现，完成编译源码、移动类文件、部署类库等操作。
• depends 构建类库和本地库时需要的一些辅助文件，本身不属于项目一部分。包括一些 JAR 包和编译好的库文件，在类库的编译和打包期间，需要这些辅助文件，可以运行 ant fetch-depends 命令自动从各个服务器下载部署这些文件。
• doc 关于 Harmony 类库的一些 HTML 文档，其中既有关于类库的，也有关于虚拟机的文档。
• modules Java 类库的源码，被划分成许多相对独立的模块。
• support 实现类库时需要的一些工具类实现和测试类实现。
• deploy构建整个源码后，脚本会新建一个 deploy 目录，类库各个模块会被打包部署在这里，生产 JRE 目录结构。不过从代码资源库检出时没有这个目录。

构建源码

为了正常构建整个 Harmony 类库以及相关的本地源码，必须正确的安装并配置下面这些工具，确保正确设置了 PATH 环境变量，使得运行环境能找到下述工具的可执行文件：

• C 编译器 在 windows 下需要安装 Microsoft(R) 32-bit C/C++ Compiler，如果你在用的时 Linux 系统，则需要安装 GNU project C/C++ Compiler(GCC)。
• Java 编译器 提供的编译器必须能处理 JDK1.5 以上的 Java 代码。
• Apache Ant 一个基于 Java 的构建工具。你可以在 http://ant.apache.org 下载并获得相关的详细信息。
• Subversion 版本控制软件，用于资源库检出文件，更新代码修改，制作补丁文件等操作，也可用集成于 Eclipse 的 Subclipse 插件。

当所有这些都具备的时候，就可以构建类库的源文件，生成的可执行文件会部署在 ${HARMONY_HOME}/deploy 目录下。${HARMONY_HOME}/build.xml 脚本提供了如下目标供构建类库时使用。

                
  ant clean
    删除所有构建时生成的文件

  ant rebuild
    先执行 ant clean，再执行 ant build

  ant test
    运行所有的单元测试

  ant doc
    生成javadoc

  ant snapshot
    生成类库的快照，即打成 tar 或 zip 包

  ant fetch-depends
    获取构建时所有的依赖文件，其中一些并非基于 Apache License v2 的

  ant -Dbuild.module={module} target
    针对任一单独模块的构建，其中 target 为 clean,rebuild,test,doc,snapshot,fetch-depends 中的任一目标
    

${HARMONY_HOME}/build.xml 实际会调用 ${HARMONY_HOME}/make 下的各个子脚本来完成任务，make 目录下各个构建脚本的功能分别为：

• make/build-java.xml： 编译 modules/${module}/src/main 目录下所有的类库源代码，生成相应的 class 文件，然后复制一份供后面的测试部分使用，最后将所有编译好的文件按照模块划分，打包成jar文件，并被部署到 deploy/jdk/jre/boot/ 目录下，也就是 bootclasspath 下。
• make/build-native.xml： 用 C 编译器编译所有的 native code，生成 java launcher（windows 下的 java.exe，linux下的 Java）和相应的共享库文件（windows 下的 dll 文件和 linux 下的 so 文件）。
• make/build-test.xml： 它会调用每个 modules 下的 make/build.xml 文件，来编译 modules/${module}/src/test 目录下的所有测试源文件，并对相应的类库 class 文件进行单元测试，生成测试报表。
• make/depends.xml： 下载构建类库时需要的一些依赖文件，并部署到前面提到的 ${HARMONY_HOME}/depends 目录下。

构建类库时，需要耗费大量内存，默认环境 Ant 环境设置可能无法满足需求，导致构建时发生 OutOfMemory 的错误。开发者可以通过配置 Ant 的环境，设置环境变量 ANT_OPTS 的值（具体数据可根据实际环境调整到更大），解决这个问题。

                
	Windows：   set ANT_OPTS=-Xms128m -Xmx256m
	Linux：   export ANT_OPTS=-Xms128m -Xmx256m
    

完成类库的构建后，仍然无法提供完整的 JRE。编译出来的类库必须配合虚拟机实现一起使用才能正常运行 class 文件。目前 Harmony 使用的虚拟机实现是由 IBM 提供的 J9 VM 的修改版本，可以和 Harmony 的类库配合使用。但是这不是一个开源软件，而是由 IBM 贡献给 Harmony 使用的，只是一个过渡用实现。Harmony 有自己的 VM 实现，那就是 DRLVM（Dynamic Runtime Layer Virtual Machine），当 DRLVM 的实现足够成熟时，Harmony 就会用 DRLVM 替换现在的 VM。实际使用时，只需要把下载的压缩包解压，把里面的 default 目录复制到 ${HARMONY_HOME}/jdk/jre/bin/ 下即可。

测试驱动开发

Harmony 项目要求独立的开发一个和 Sun JDK 兼容的 JAVA 运行时环境。为了保证得到一个独立开发的，干净的 JDK 实现，Harmony 项目采用了一种独特的开发模式，即测试驱动开发技术。首先，Harmony 的需求就是 Sun JDK 的规约，Harmony 项目开发出来的 JDK 的行为必须与规约上描述的一致。但是，有的时候规约上的描述并不确切，或者十分模糊。Harmony 社区开发者不能通过阅读 Sun JDK 的源代码来了解类的行为，而是应该通过开发测试用例的方法自己找出该类行为的实际情况。列表1给出了从 JDK5 的 spec 中 DecimalFormat 摘录的一段关于 DecimalFormat 的构造函数抛出异常的描述。

                
Throws:
    NullPointerException - if any of the given arguments is null 
    IllegalArgumentException - if the given pattern is invalid
      

当构造一个 DecimalFormat 的时候，如果传递了一个无效的 pattern 同时传递的 symbols 为 null，从这段描述中看不出来 NullPointerException 会先被抛出还是 IllegalArgumentException 会先被抛出。在这样的情况之下就需要写一个测试用例，明确的判断这个情况。列表2给出了一个判断哪个异常会被先抛出的测试用例。

                
public void testConstructor() {
	try {
		DecimalFormat format = new DecimalFormat("test", null);
	} catch (NullPointerException e) {
		// expected
	}
}
      

在 SUN JDK 上运行这个测试用例，该测试用例通过。可以得出结论，SUN JDK 的行为如下：当 NullPointerException 和 IllegalArgumentException 都有可能被抛出的时候，NullPointerException 会被首先抛出。在开发 Harmony JDK 的时候，为了保证 NullPointerException 会被首先抛出，开发人员增加了以下代码。

                
if (symbols == null) throw new NullPointerException();
    

使用邮件组进行讨论

Harmony 是一个开源项目，该项目吸引了来自世界各地的开发者。这就需要一个供大家进行集中讨论的地点。在 Apache 的所有项目中，邮件组（mailing list）是一个十分常用的手段。Harmony 项目给开发者提供了两个用于开发的邮件组，分别是开发者邮件组 dev@harmony.apache.org 和源代码控制邮件组 commits@harmony.apache.org。开发者邮件组供开发者讨论开发计划，做出设计决定，还可以针对某些技术问题举行投票。当 JIRA 系统中有更新，也会自动发邮件到该邮件组。当任何的改动被提交到 Harmony 源代码树中时，源代码控制邮件组将会收到邮件，同时 Harmony Wiki 中的变动也会反映到源代码控制邮件组中。这样将邮件组和版本控制系统以及缺陷跟踪系统结合起来，大大的提高了项目开发过程之中信息的整合。使得系统中任何的变动都可以被集中的反映给所有人，提高了项目的透明度。图14显示订阅了开发者邮件组的邮件收件箱。

使用 JIRA 参与开发

JIRA 是由 Atlassian 开发的基于 J2EE 的问题跟踪管理系统。它没有 Bugzilla 仅能管理 Bug 的局限，而是集合项目计划、任务分配、需求管理、错误跟踪等多种功能于一体。JIRA 默认支持 New Feature、Bug、Task和Improvement 四种问题（Issue）类型。不仅如此，它还支持自定义问题，自定义开发流程，所以还能运用于过程管理。虽然 JIRA 是一款商业软件，但开源项目可以免费使用它，所以世界各地有很多开源项目使用 JIRA 来管理项目开发，Apache 也是其中之一。Harmony 作为 Apache 的一个项目，使用 Apache 项目 JIRA 系统的一个子模块管理 Harmony 项目，它配合邮件组的使用能够使整个社区的开发者通过 Web 方便的知道项目的状况和进度。并且项目管理者也能够方便的管理分散在世界各地的开发者。在 Harmony 中任何一个臭虫（bug），新功能，结构改动（refactor），都会产生一个新 JIRA 记录。

开发者如果要参与到 Harmony 项目中来，必须通过 JIRA 系统与社区中的其他开发人员交流合作。对于 JIRA 上的所有问题（ISSUE），都需要经过通过三个步骤。

报告问题 （Reporting Issues）

开发者可以通过一个尽可能简洁明了的测试程序来说明碰到的问题，因为代码就是程序员间交流的最佳途径。在报告新问题的时候，最好能直接附带一个测试程序的补丁，补丁可以通过 Subversion 里的 diff 工具生成，并能直接应用到 Harmony 的源码上，这样开发社区里其他开发者就无需自己重新修改代码，使项目维护更为高效。
用 svn 命令制作补丁文件

                    
	svn diff file.java > file.patch
    

解决问题 （Resolving Issues）

为了解决一个新报告的问题，开发者首先要确认问题的类型，做到有的放矢。问题的种类分两种，一种是臭虫（bug），需要提供修复补丁；而另一种则只是实现上的行为差异（non-bug difference），类库的规格（SPEC）只有一个，Sun JDK 提供的类库实现是官方标准实现（Reference Implementation，简称为 RI），但针对同一个规格，由于算法的不同，可以有多种不同的实现，在这种情况下，开发者无需提供修复补丁，只需注明行为差异，开发社区会讨论决定最后的解决方案。

如果开发者确认问题的类型确实是 Harmony 实现的一个臭虫，那就需要按如下步骤执行。

首先，在感兴趣的问题上添加注释，并在开发者的邮件组（mailing list）上发信，通知社区里其他开发人员有人正在关注这个问题，即认领这个问题。这样做既方便开发人员们一起讨论交流，也避免了无谓的重复劳动。如果报告问题的开发者没有提供含测试代码的补丁，可以根据当前 JIRA 上已经提供的描述信息，尝试着重现问题，并以补丁的形式上传相关的测试代码。重现问题后，可以尝试修复这个问题，在本地代码上进行调试，当通过测试后，根据修改的代码制作相应的修复补丁。在上传补丁之前，需要特别注意的就是，务必确保补丁能分别在 Windows 和 Linux 两个平台下（harmony 计划支持更多的平台，读者可以在 harmony 项目的维基页上查找），成功运行所有的单元测试，防止副作用，导致其他测试程序失败。只有所有的测试程序都通过了，才能把补丁上传到 JIRA 上。如果开发者对自己的解决方法仍存有疑虑或者没有十足把握的话，可以在开发者邮件组上发信和其他开发者进行讨论，从社区的其他开发者那里获取有价值的意见建议，然后把讨论的结果链接到当前问题，还可以把一些相关问题也链接在一起供大家参考。

对于补丁文件，还有几点需要注意。首先，无论是含有测试代码的补丁，还是含有修复代码的补丁，都需要把路径设为相对路径，要以相应模块的目录作为根目录，不然别的开发人员可能无法应用这个补丁。其次，测试和修复补丁需要分开保存，作为不同的补丁文件上传。如果这个补丁需要对代码库里的源文件进行添加，删除或者移动操作的话，建议最好同时提供相应的脚本文件完成这些操作。

                
	svn add relative-path/file.java
	svn del relative-path/file.java
    

最后，一个修复补丁最好只修复一个单一问题，越简单越好，这即控制了代码的数量，也便于其他开发者更好的复查代码，早点发现问题，越早发现问题，补救的代价就越低。如果开发者暂时无法提供相应的测试补丁或者修复补丁，可以把测试代码和修复代码甚至伪代码直接添加到 JIRA 的注释里，供其他开发人员参考。

还有一些时候，问题可能是由于 Harmony 和 RI 的具体实现不一致而引起，并不存在明显的对错界限，这种类型的问题就应该和臭虫区别对待。可以在开发者邮件组上发信讨论这个问题，然后把相关讨论的结果链接到这个问题下。

关闭问题 （Closing Issues）

如果社区讨论得出的结论确认问题不是一个臭虫，而只是一个实现上的行为差异，可以直接关闭这个问题。 相反，如果这个问题确实是一个臭虫，就需要按照下面的步骤执行。如果有测试补丁，把这个补丁应用到 Harmony 的源码上，验证测试程序是否确实运行失败。 然后，再应用修复补丁到源码上，重新执行一遍前面的测试程序，这时测试程序应该能成功运行。不过这还不能表明问题已经得到了修复，开发者还需要确保应用补丁后，所有其他已经存在的单元测试都能运行通过。如果前面任意步骤遇到问题的话，可以在 JIRA 上添加注释，让其他人来解决。最后，如果一切运行顺利，就在 JIRA 上添加当前的版本控制号信息，方便以后出现问题时回溯源码。

Harmony 做为一个开源项目，在邮件组和 JIRA 的使用上就能很好的体现其开放的精神。所以问题的解决都可以也有必要在邮件组上进行讨论，在无数双眼睛的注视下，让问题无处藏身。

基于维基（Wiki）的文档

Harmony 除了在 Apache 主页上提供的相对稳定的文档外，还维护了一些随项目开发进程动态更新的文档，这就是在 Harmony 网站上基于维基网页形式维护的文档。

Harmony 使用 MoinMoin Wiki 引擎，这是一个基于 GNU GPL 的开源软件。同源码由开源社区中众多程序员共同开发类似，文档也可以面向社区，由大家共同协作维护。没有单一作者，人人可以修改上面的内容，体现了自由、开放、协作的精神。同时，无法避免的是，这回对文档造成一些有意或无意的破坏。因此 MoinMoin Wiki 本身带有类似于 SVN 版本控制的功能，记录了所有人的修改，你不仅可以看到先前所有人做的修改，同时也可以回复到先前的任一正常状态，这保证了 Wiki 的正常维护。在登录到 Harmony 的 Wiki 上后才能进行修改，同时点击 Get Info 就进行页面的版本控制。

如图所示，开发者不仅能看到修改时间，修改用户，还能看到对操作的注解，极大方便了社区对文档的维护。

结束语

Apache Harmony 作为一个开源项目，在整个开发过程中都体现着开放的特性，其所有的基础设施也均为这个目标而服务。但是开放并不意味着没有规范，开发过程中，开发者需要严格遵守开源项目的一般流程，只有熟悉具体项目的基础设施，社区才能高效的接受其贡献的代码，反之，则会大大增加项目维护的开销。

参考资料

• 阅读 进入 Harmony 世界 系列文章的其它部分。
  
  
• 从 Apache Harmony 项目的 官方网站 中获得更多相关信息。
  
  
• 了解 Harmony 的类库 API 的覆盖率统计报告： JDK 1.4、JDK 1.5。
  
  
• 如何 参与 到 Apache Harmony 项目。
  
  
• 定制 bugzilla 进行项目管理（developerWorks Java，2006 年 10 月）： 介绍了如何在 Apache Harmony 项目中使用流行的缺陷跟踪系统 — Bugzilla。
  
  
• 追求代码质量 专栏：来自质量专家 Andrew Glover 关于测试覆盖工具方面的专家意见。
  
  
• 让开发自动化 专栏：专门探索软件开发过程自动化的实际应用。
  
  
• Harmony 网站上基于 维基 网页形式维护的文档。
  
  

• Apache Harmony 的二进制版本 下载。
  
  
• IBM Apache Harmony 开发包（VM Environment） 下载。
  
  
• IBM JDK 下载。

作者简介

		邱小侠 (qiuxiaoxia@gmail.com), 对 Open Source 项目和 Java 编程有浓厚的兴趣。

		沈羽,软件工程师，对 C/C++ 编程有浓厚的兴趣。

对本文的评价

太差！ (1) 需提高 (2) 一般；尚可 (3) 好文章 (4) 真棒！(5) 建议？

回页首