统一的Build平台使用指南
一、 CruiseControl简介
CruiseControl是目前常用的持续集成框架,它能够与VSS、CleasCase、CVS等主流配置库管理工具集成,以实现配置库代码变更自动发现,自动触发build,定时触发build,对每次build过程中生成的文件、报告等能够进行集成化管理,便于查询历史build记录。CruiseControl内嵌有WEB服务器程序Jetty,对build结果提供站点自动发布功能。
二、 统一的Build平台简介
本Build平台,基于CruiseControl,集成了CheckStyle、PMD、FindBugs、JUnit、Cobertura等工具,能够完成自动获取配置库代码、代码规范性检查、重复代码检查、编译、静态检查、自动化测试、覆盖率分析等,并将build结果以多维的方式进行站点发布。
三、 安装指南
以下我们以Windows操作系统为例,其它操作系统类同,配置库以CVS为例。
(1) 解压CruiseControl.rar到一指定目录,例如:c:\,将会有C:\CruiseControl目录。
(2) 安装CVSNT,并将cvs.exe路径加入path环境变量。
(3) 安装JDK,设置JAVA_HOME环境变量指定JDK位置。
(4) 设置CVSROOT环境变量。例如:
:pserver:t21911:12345678@127.0.0.1:D:/cvsfile
(5) 假如你的代码在cvs库的example150cc模块中,在配置库example150cc目录下创建我们为你提供的build.xml文件,并修改该文件中相关的属性,如源代码位置、测试代码位置等以适应你的项目。
(6) 启动cmd,C:\CruiseControl\projects目录下运行cvs checkout example150cc,将你项目的配置库代码checkout到当前目录,只做一次,以后就不用再做了。
(7) 修改C:\CruiseControl目录下的两个文件:config.xml、build.xml以适应你的项目。
注:在CruiseControl\projects\example150cc目录下有我们提供的例子配置库代码,也就是cvs配置库example150cc模块的内容。
四、 build.xml文件属性说明
(1) source.dir:你的源代码目录。
(2) test.dir:你的测试代码目录,该目录下含有基于JUnit的测试代码。该目录也可以是一个空目录(如果你不想做测试的话)。
(3) report.dir:build过程中输出的报告的存放目录,报告包括:CheckStyle报告、PMD报告、Copy/Paste报告、FindBugs报告、测试报告、覆盖率检查报告,每类报告以单独的子目录存放。
(4) extlib.dir:本build平台用到的相关类库,如Cobertura、CheckStyle、PMD等,请不用修改该属性。
(5) masterlib.dir:你的源代码或测试代码依赖的相关类库,也就是你编译时的CLASSPATH,请注意修改此属性,以适应你的项目。
(6) findbugs.home:FindBugs安装目录,本Build平台已提供,无需修改此属性。
另外请注意修改build.xml文件中以下红色部分的目录路径与你的环境一致(因PMD对此处的相对路径有特殊意义,所以无法做成相对路径,见谅!):
<targetname="pmd"depends="checkstyle">
<echo>正在对源代码进行PMD静态检查...</echo>
<pmdrulesetfiles="C:/CruiseControl/xml/pmd_ruleset_minimal.xml"shortFilenames="true">
<formattertype="xml"tofile="${pmd.dir}/${pmd.report}"/>
<filesetdir="${source.dir}">
<includename="**/*.java"/>
</fileset>
</pmd>
<xsltin="${pmd.dir}/${pmd.report}"out="${pmd.dir}/index.html"style="../../xml/wz-pmd-report.xslt"/>
</target>
五、 使用说明
(1)启动CruiseControl
启动cmd,进入C:\CruiseControl目录,运行:cruisecontrol.bat。将启动WEB服务器等待build。
(2)查看build结果
打开游览器,输入地址:http://localhost:8080/,如果在远程请将localhost换成对应的IP地址。
六、 其它注意事项
(1) 如何与ClearCase整合
u config.xml文件
以下代码加在modificationset元素下,用于告诉CruiseControl监控哪个配置库更新,以触发build。
<clearcase branch="main" viewpath="E:\CC\j63589_view\IN_FINNY_VOB\
项目库
\LACV100R001C01B02_CODE\WSMAP" />
其中viewpath指的是你配置库的本地目录路径,一直到你代码所在的project。
u enter_build.xml文件
以下代码用于获取配置库最新代码。
<ccupdate viewpath="E:\CC\j63589_view\IN_FINNY_VOB\
项目库
\LACV100R001C01B02_CODE\WSMAP"
graphical="false"
log="log.log"
overwrite="true"
currenttime="true"
rename="false"/>
注意:以上两个文件如果有中文,请在文件开头设定你的编码格式。
<?xml version="1.0" encoding="GBK"?>
(2) 如何与VSS整合
需要改两个地方
u config.xml
将modificationset下的cvs换成vss,参数配置详见cruisecontrol的帮助。
u enter_build.xml
将其中的cvs换成vssget,参数配置详见ANT帮助。
(3) 几个检查规则文件介绍
规则文件在xml目录下:
checkstyle_ruleset_minimal.xml—CheckStyle检查规则文件,侧重于编程规范,去除了PMD能够重复检查到的缺陷规则。
pmd_ruleset_minimal.xml—PMD检查规则文件,仅限推荐指数3、4、5的规则、去除了FindBugs和CheckStyle能发现的大部分重复问题(有少量重复)、去除了AvoidDuplicateLiterals规则。(限PMD4.2以上版本使用)
(4) Findbugs的规则文件在哪儿
Cruisecontrol/findbugs-1.2.1/plugin/coreplugin.jar压缩包中的findbugs.xml
(5) 如何定义build在某固定时间点触发
修改config.xml文件。有三种触发build策略选择:
第一种:根据配置库是否有checkin代码触发build,还可以调节平静期(quietperiod),也就是说它可以很好地解决频繁checkin的情况。
<modificationset quietperiod="20">
<cvs localworkingcopy="projects/${project.name}" />
</modificationset>
<schedule interval="25">
<ant anthome="apache-ant-1.7.0" buildfile="enter_build.xml" target="build" uselogger="true" usedebug="false" />
</schedule>
第二种:每天固定时间build,以下配置的time表示在每天的11:46定时build
<schedule>
<ant anthome="apache-ant-1.7.0" buildfile="enter_build.xml" target="build" uselogger="true" usedebug="false" time="1146" />
</schedule>
第三种:手工触发build
(6) 启动时报OutOfMemory错误,怎么解决
cruisecontrol.bat文件有以下行,请去掉注释,并将堆空间调大一点,比如512m
REM set CC_OPTS=-Xms128m -Xmx256m
(7) FindBugs检查时报OutOfMemory错误,怎么解决
修改build.xml文件中的以下红色项,参数调大一点。
<findbugs home="${findbugs.home}" jvmargs="-Xms256m -Xmx512m" reportLevel="low" output="xml:withMessages" outputFile="${findbugs.dir}/${findbugs.report}">
(8) 报异常找不到org/apache/log4j/Category类
把log4j的JAR包放到ant的lib目录下。
(9) PMD的中文目录处理
如果被检查源代码所属Project位于中文目录名路径下,PMD的输出报告中会有中文编码的问题,解决办法是在输出报告中取短路径名,也就是相对路径名,这样也可缩短报告的字节数。
<pmd rulesetfiles="basic,unusedcode,braces,design,controversial,imports,clone,codesize,naming"
shortFilenames="true"
>
<formatter type="xml" tofile="${pmd.dir}/${pmd.report}"/>
<fileset dir="${source.dir}">
<include name="**/*.java"/>
</fileset>
</pmd>
(10) 检查报告所占屏幕空间太小
从以下入口进入可看到全屏的结果(部分报告的显示格式会有不同):
(11) 报以下错误,如何解决
pmd:
[echo] 正在对源代码进行PMD静态检查...
[xslt] Processing E:\Software Engineer\Unite Build Platform\CruiseControl\projects\sqm\report\pmd\pmd_report-20080604-1034.xml to E:\Software Engineer\Unite Build Platform\CruiseControl\projects\sqm\report\pmd\index.html
[xslt] Loading stylesheet E:\Software Engineer\Unite Build Platform\CruiseControl\xml\wz-pmd-report.xslt
[xslt] : Error! The entity "u923d" was referenced, but not declared.
[xslt] : Error! com.sun.org.apache.xml.internal.utils.WrappedRuntimeException: The entity "u923d" was referenced, but not declared.
[xslt] Failed to process E:\Software Engineer\Unite Build Platform\CruiseControl\projects\sqm\report\pmd\pmd_report-20080604-1034.xml
答:CruiseControl\xml\pmd_ruleset_minimal.xml,将此文件中的AvoidDuplicateLiterals规则去除。
(12) 浏览器访问时报错org/apache/jsp/main_jsp (Unsupported major.minor version 49.0),如何解决
答:这个错误的原因是用低版本的jdk去跑了高版本的jdk编译出来的class文件,49.0是jdk1.5的主次版本号。此时将安装目录CruiseControl\webapps\cruisecontrol\WEB-INF\work下的org目录删除即可。
注:(1)我们提供的压缩包里已经将work下的org目录删除了。(2)系统默认支持JDK1.5版本,我们无法保证PMD在JDK1.4版本下能够正常使用,build时可能会报错java.lang.UnsupportedClassVersionError: net/sourceforge/pmd/ant/PMDTask (Unsupported major.minor version 49.0),所以此时最好从build.xml文件将有关PMD内容删除。(3)我们提供的例子配置库代码因为使用了JDK1.5的新特性,无法在JDK1.4下使用。
(13) 如何查看build输出信息
答:以下文件记录了build时的输出信息:
CruiseControl/antBuilderOutput.log
(14) 统一Build平台如何避免OutOfMemory错误
5个可选的解决办法:
(1)增加机器配置,调大参数set CC_OPTS=-Xms512m -Xmx1024m。
(2)去除一些规则
(3)缩小代码检查范围,限定在只关心的部分:
<pmd rulesetfiles="C:/CruiseControl/xml/pmd_ruleset_minimal.xml" shortFilenames="true">
<formatter type="xml" tofile="${pmd.dir}/${pmd.report}"/>
<fileset dir="${source.dir}">
<include name="**/*.java"/>
</fileset>
</pmd>
(4)checkin到配置库的代码确保有较少的问题
(5)先不用PMD或CheckStyle
(15) 自动化测试时报junitvmwatcher**.properties文件找不到的问题解决
在用JUnit做自动化测试时如果报以下错误:
test:
[echo] 正在执行测试...
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.25 sec
[junit] java.io.FileNotFoundException: C:\CruiseControl\projects\cvsroot\Alm\junitvmwatcher1101455943.properties (系统找不到指定的文件。)
[junit] at java.io.FileInputStream.open(Native Method)
[junit] at java.io.FileInputStream.<init>(FileInputStream.java:106)
英文版错误:
test:
[echo] 正在执行测试...
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.25 sec
[junit] java.io.FileNotFoundException: C:\CruiseControl\projects\cvsroot\Alm\junitvmwatcher1101455943.properties (The system cannot find the file specified)
[junit] at java.io.FileInputStream.open(Native Method)
[junit] at java.io.FileInputStream.<init>(FileInputStream.java:106)
解答:这是由于ANT的版本冲突造成的,例如可能你启动的ANT版本是1.7.0,而你运行测试时的CLASSPATH路径中含有了1.6.5版本的ANTjar包,由于ANT版本的不兼容性造成了以上错误,所以解决此问题的办法是确保你的运行环境只存在一个版本的ANT。