ANT 最佳实践

ANT 最佳实践 (OSSEZ) CHS 技术参考, 2011-06-24 Author: YUCHENG HU, HA Websystems, Inc. OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 1 / 18 备忘 Copyright © HA WEBSYSTEMS 2006–2011. 版权所有 URLs 参考: http://www.hawebs.net http://www.hawebs.org 技术支持: http://www.ossez.com 知识产权: HA WEBSYSTEMS 罕布什尔 (中国) 信息技术有限公司及作者持有本文档的所有权 相关工作: 技术文档格式化版本 摘要: N/A 状态: N/A ODT 发行版本 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 2 / 18 目 录 1 采用一致的编码规范..................................................................................................................... 4 2 将 build.xml 放在项目根目录中.....................................................................................................5 3 使用单一构建文件........................................................................................................................ 6 4 提供良好的帮助说明..................................................................................................................... 7 5 提供清空任务............................................................................................................................... 8 6 使用 ANT 管理任务从属关系........................................................................................................9 7 定义并重用文件路径...................................................................................................................10 8 定义恰当的任务参数关系...........................................................................................................11 9 使用配置属性............................................................................................................................. 12 10 保持构建过程独立 ..................................................................................................................13 11 使用版本控制系统.................................................................................................................... 14 12 把 Ant作为“最小公分母”......................................................................................................15 13 使用 zipfileset 属性.................................................................................................................. 16 14 运行 Clean 构建任务的测试.....................................................................................................17 15 Avoid Platform-Specific Ant Wrappers ....................................................................................18 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 3 / 18 1采用一致的编码规范 Ant 用户不管是喜欢还是痛恨 XML 构建文件的语法，都愿意跳进这一迷人的争论 中。 让我们先看一些保持 XML 构建文件简洁的方法。 首先，也是最重要的，花费时间格式化你的 XML 让它看上去很清晰。 不过 XML 是否美观，Ant 都可以工作。 但是丑陋的 XML 很难读懂。 倘若你在任务之间留出空行，有规则的缩进，每行文字不超过 90 列，那么 XML 令 人惊讶的易读。 再加上好的编辑器或 IDE 高亮相应的语句，你就不会有如何阅读的麻烦。 同样，精选有意义明确、容易读懂的词汇来命名任务和属性。 比如，dir.reports 就比 rpts 好。并不需要特定的编码规范，只要有一种规范并坚持 使用就好。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 4 / 18 2将 build.xml 放在项目根目录中 Ant 构建文件 build.xml 可以放在如何位置，但是放在项目顶层目录中可以保持项 目简洁。 这是最普遍的规范，使开发者能够在根目录找到它。 同时，也能够容易了解项目中不同目录之间的逻辑关系。 以下是一个典型的项目层次： [root dir] | build.xml +--src +--lib (包含第三方 JAR包) +--build (由 build任务生成) +--dist (由 build任务生成) 当 build.xml 在顶级目录时，倘若你在项目某个子目录中，只要输入：ant -find compile 命令，不需要改变工作目录就能够以命令行方式编译代码。 参数-find告诉 Ant寻找存在于上级目录中的 build.xml 并执行。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 5 / 18 1 2 3 4 5 3使用单一构建文件 有人喜欢将一个大项目分解到几个小的构建文件，每个构建文件分担整个构建过程 的一小部分工作。 但是应该认识到，将构建文件分割会增加对整个构建过程的理解难度。 要注意在单一构建文件能够清楚表现构建层次的情况下，不要过工程化(over- engineer)。 即 使你把项目划分为多个构建文件，也应使程序员能够在项目根目录下找到核心 build.xml。 尽管该文件只是将实际构建工作委派给下级构建文件，也应保证该文件可用。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 6 / 18 4提供良好的帮助说明 应尽量使构建文件自文档化。增加任务描述是最简单的方法。 当你输入 ant -projecthelp 时，你就可以看到带有描述的任务清单。 比如，你可以这样定义任务： 最简单的规则是对所有你希望程序员通过命令行直接调用的任务都加上描述。 对于一般用来执行中间处理过程的内部任务，比如生成代码或建立输出目录等，就 无法使用描述属性。 这时，可以通过在构建文件中加入 XML注释来处理。 或者专门定义一个 help 任务，当程序员输入 ant help 时来显示详细的使用说明。 Detailed help... OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 7 / 18 6 7 8 9 10 11 5提供清空任务 每个构建文件都应包含一个清空任务，删除所有生成的文件和目录，使系统回到构 建文件执行前的初始状态。 执行清空任务后还存在的文件应处在版本控制系统的管理下。 除非是在产生整个系统版本的特殊任务中，否则不要自动调用 clean 任务。 当程序员仅仅执行编译任务或其他任务时，他们不需要构建文件事先执行即令人讨 厌有没有必要的清空任务。 要相信程序员能够确定何时需要清空所有文件。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 8 / 18 12 13 14 15 16 6使用 ANT 管理任务从属关系 假设你的应用由 Swing GUI组件、Web界面、EJB 层和公共应用代码组成。 在大型系统中，你需要清晰地定义 Java 包属于系统的哪一层。 否则如何一点修改都要重新编译成千上百个文件。 任务从属关系管理差会导致过度复杂而脆弱的系统。 改变 GUI面板的 设计 领导形象设计圆作业设计ao工艺污水处理厂设计附属工程施工组织设计清扫机器人结构设计 不应造成 Servlet 和 EJB 的重编译。 当系统变得庞大后，稍不注意就可能将依赖于客户端的代码引入到服务端。 这是因为 IDE 在编译文件时使用单一的 classpath。 Ant 让你更有效地控制构建活动。 设计你的构建文件编译大型项目的步骤：首先，编译公共应用代码，将编译结果打 成 JAR 包文件。 然后，编译上一层的项目代码，编译时依靠第一步产生的 JAR 文件。 不断重复这一过程，直到最高层的代码编译完成。 分步构建强化了任务从属关系管理。 如果你工作在底层 Java框架上，引用高层的 GUI模板组件，这时代码不需要编译。 这是由于构建文件在编译底层框架时，在源路径中没有包含高层 GUI面板组件的 代码。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 9 / 18 7定义并重用文件路径 如果文件路径在一个地方集中定义，并在整个构建文件中得到重用，那么构建文件 更易于理解。 以下是这样做的一个例子： ...etc 当项目不断增长，构建日益复杂时，这一技术越发体现出其价值。 你可能为编译不同层次的应用定义各自的文件路径，比如运行单元测试的、运行应 用程序的、运行 Xdoclet 的、生成 JavaDocs 的等等不同路径。 这种组件化路径定义的方法比为每个任务单独定义路径要优越得多。 否则，很容易丢失任务任务从属关系的轨迹。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 10 / 18 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 8定义恰当的任务参数关系 假设 dist 任务从属于 jar 任务，那么哪个任务从属于 compile 任务，哪个任务从属 于 prepare 任务呢？ Ant 构建文件最终定义了任务的从属关系图，它必须被仔细地定义和维护。 应该定期检查任务的从属关系以保证构建工作得到正确执行。 大的构建文件随着时间推移趋向于增加更多的任务，所以到最后由于不必要的从属 关系导致构建工作非常困难。 比如，你可能发现在程序员只是需要编译一些没有使用 EJB 的 GUI 代码时，重新生 成 EJB 代码。 以“优化”的名义忽略任务的从属关系是另一种常见的错误。 这种错误迫使程序员为了得到恰当的结果必须记住并按照特定的顺序调用一串任务。 更好的做法是：提供描述清晰的公共任务，这些任务包含正确的任务从属关系；另 外提供一套“专家”任务让你能够手工执行个别的构建步骤，这些任务不提供完整 的构建过程，但是让那些专家在快速而恼人的编码期间跳过某些步骤。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 11 / 18 9使用配置属性 任何需要配置或可能发生变化的信息都应作为 Ant 属性定义下来。 对于在构建文件中多次出现的值也同样处理。属性既可以在构建文件头部定义，也 可以为了更好的灵活性而在单独的属性文件中定义。 以下是在构建文件中定义属性的样式： etc... 或者你可以使用属性文件： etc... 在属性文件 sample.properties 中: dir.build=build dir.src=src jdom.home=../java-tools/jdom-b8 jdom.jar=jdom.jar jdom.jar.withpath=${jdom.home}/build/${jdom.jar} 用一个独立的文件定义属性是有好处的，它可以清晰地定义构建中的可配置部分。 另外，在开发者工作在不同操作系统的情况下，你可以在不同的平台上提供该文件 的不同版本。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 12 / 18 33 34 35 36 37 38 39 40 41 42 43 44 45 46 10 保持构建过程独立 为了最大限度的扩展性，不要应用外部路径和库文件。 最重要的是不要依赖于程序员的 CLASSPATH设置。 取而代之的是，在构建文件中使用相对路径并定义自己的路径。 如果你引用了绝对路径如 C:\java\tools，其他开发者未必使用与你相同的目录结构， 所以就无法使用你的构建文件 如果你部署开发源码项目，应该提供包括所有需要 的 JAR 文件的发行版本，当然是在遵守 许可 商标使用许可商标使用许可商标使用许可商标使用许可商标使用许可 协议 离婚协议模板下载合伙人协议 下载渠道分销协议免费下载敬业协议下载授课协议下载 的基础上。 对于内部项目，相关的 JAR 文件都应在版本控制系统的管理中，并捡出到大家都 知道的位置。 当你不得不应用外部路径时，应将路径定义为属性。使程序员能够 涌适合他们自己的机器的参数重载这些属性。 你也可以使用以下语法引用环境变量： OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 13 / 18 47 48 11 使用版本控制系统 构建文件是一个重要的文件，应该象代码一样进行版本控制。 当你标记你的代码时，也应用同样的标签标记构建文件。 这样当你需要回溯构建旧版本的软件时，能够使用相对应的旧版本构建文件。 除构建文件之外，你还应在版本控制中维护第三方 JAR 文件。 同样，这使你能够重新构建旧版本的软件。 这也能够更容易保证所有开发者拥有一致的 JAR 文件，因为他们都是同构建文件 一起从版本控制系统中捡出的。 通常应避免在版本控制系统中存放构建输出品。 倘若你的源代码很好地得到了版本控制，那么通过构建过程你能够重新生成任何版 本的产品。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 14 / 18 12 把 Ant作为“最小公分母” 假设你的开发团队使用 IDE，为什么要为程序员通过点击图标就能够构建整个应用 而烦恼呢？ IDE 的问题在团队中是一个关于一致性和重现性的问题。 几乎所有的 IDE设计初衷都是为了提高程序员的个人生产率，而不是开发团队的持 续构建。 典型的 IDE 要求每个程序员定义自己的项目文件。 程序员可能拥有不同的目录结构，可能使用不同版本的库文件，还可能工作在不同 的平台上。 这将导致出现这种情况：在 A 那里运行良好的代码，到 B 那里就无法运行。 不管你的开发团队使用何种 IDE，一定要建立所有程序员都能够使用的 Ant 构建文 件。 要建立一个程序员在将新代码提交版本控制系统前必须执行 Ant 构建文件的规则。 这将确保代码是经过同一个 Ant 构建文件构建的。 当出现问题时，要使用项目 标准 excel标准偏差excel标准偏差函数exl标准差函数国标检验抽样标准表免费下载红头文件格式标准下载 的 Ant 构建文件，而不是通过某个 IDE 来执行一个 干净的构建。 程序员可以自由选择任何他们习惯使用的 IDE。 但是 Ant 应作为公共基线以保证永远是可构建的。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 15 / 18 13 使用 zipfileset 属性 人们经常使用 Ant 产生 WAR、JAR、ZIP 和 EAR 文件。 这些文件通常都要求有一个特定的内部目录结构，但其往往与你的源代码和编译环 境的目录结构不匹配。 一个最常用的方法是写一个 Ant 任务按照期望的目录结构把一大堆文件拷贝到临时 目录中，然后生成压缩文件。 这不是最有效的方法。 使用 zipfileset 属性是更好的解决 方案 气瓶 现场处置方案 .pdf气瓶 现场处置方案 .doc见习基地管理方案.doc关于群访事件的化解方案建筑工地扬尘治理专项方案下载 。 它让你从任何位置选择文件，然后把它们按照不同目录结构放进压缩文件中。 以下是一个例子： 在这个例子中，所有 JAR 文件都放在 EAR 文件包的 lib 目录中。 hr.jar 和 billing.jar 是从构建目录拷贝过来的。 因此我们使用 zipfileset 属性把它们移动到 EAR 文件包内部的 lib 目录。 Prefix 属性指定了其在 EAR 文件中的目标路径。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 16 / 18 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 14 运行 Clean 构建任务的测试 假设你的构建文件中有 clean 和 compile 的任务，执行以下的测试。 第一步，执行 ant clean； 第二步，执行 ant compile； 第三步，再执行 ant compile。 第三步应该不作任何事情。 如果文件再次被编译，说明你的构建文件有问题。 构建文件应该只在与输出文件相关联的输入文件发生变化时，才应该执行任务。一 个构建文件在不必执行诸如编译、拷贝或其他工作任务的时候执行这些等任务是低 效的。 当项目规模增长时，即使是小的低效工作也会成为大的问题。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 17 / 18 15 Avoid Platform-Specific Ant Wrappers 不管什么原因，有人喜欢用简单的、名称叫做 compile 之类的批文件或脚本装载他 们的产品。 当你去看脚本的内容，你会发现以下内容： ant compile 其实开发人员熟悉 Ant， 并且完全能够自己键入 ant compile。 请不要仅仅为了调用 Ant而使用特定平台的脚本。 这只会使其他人在首次使用你的脚本时，增加学习和理解的烦扰。 除此之外，你不可能提供适用于每个操作系统的脚本，这是真正烦扰其他用户的地 方。 总结 太多的公司依靠手工方法和程序来编译代码和生成软件发布版本。 那些不使用 Ant 或类似工具定义构建过程的开发团队，花费了令人惊异的时间来捕 捉代码编译过程中出现的问题，这些在某些开发者那里编译成功的代码，到另一些 开发者那里却失败了。 生 成并维护构建脚本不是一项迷人的工作，但却是一项必需的工作。 OSSEZ.COM-v1.1-Technology.ott 2011-06-24 版权所有 © HA WEBSYSTEMS 2006 - 2011 18 / 18 1 采用一致的编码规范 2 将build.xml 放在项目根目录中 3 使用单一构建文件 4 提供良好的帮助说明 5 提供清空任务 6 使用ANT管理任务从属关系 7 定义并重用文件路径 8 定义恰当的任务参数关系 9 使用配置属性 10 保持构建过程独立 11 使用版本控制系统 12 把Ant作为“最小公分母” 13 使用 zipfileset属性 14 运行 Clean 构建任务的测试 15 Avoid Platform-Specific Ant Wrappers