自动化构建实践之CruiseControl

我们使用 ClearCase 作为配置管理工具， ANT 作为 build 工具，使用 CruiseControl 自带的 Jetty 作为 Web 容器。以 CruiseControl 自带的 HelloWorld 例子为例。这里使用的是最新版本 cruisecontrol-bin-2.7.1-RC1.zip

1.1        准备工作

1.          安装相关的软件：

a)          JDK ：这里我们使用的是 jdk1.5

b)         ClearCase ：这里我们采用 NativeClient 方式，可以是静态视图也可以是动态视图。通过 CCRC 创建的视图由于不能执行命令行方式，不能通过执行 cleartool update 获取到资源的最新成果， CruiseControl 不能使用 CCRC 方式来进行使用。

c)         安装 CruiseControl ：执行 CruiseControl-2.7.1-RC1.exe 或解压 cruisecontrol-bin-2.7.1-RC1.zip 都可以

d)         复制 docs\main 下的 helloworld 目录到相应的 ClearCase 的 vob 下，保留 src 目录和 clearcase-build.xml 文件，修改文件名 clearcase-build.xml 为 build.xml ，其他的全部删除。然后，把这些保留的文件提交到 ClearCase 配置库。注意：这些文件的原始文件还保留在 docs\main 下，这样以后需要的话还可以使用。

2.          配置环境变量

a)          JAVA_HOME

1.2        CruiseControl 目录结构

1)         cruisecontrol.bat ：启动文件

2)         config.xml ：配置文件（默认的配置文件名称）

3)         apache-ant-1.6.5 ： CruiseControl 自带的 ant 环境， CruiseControl 要借助 ant 完成一些指定的任务

4)         docs ：包括 CruiseControl 的使用文档和一个 helloworld 的使用范例

5)         lib ：运行需要的 jar 包

6)         logs ：日志目录，报告中的项目日志存放位置，可以通过 \webapps\cruisecontrol\WEB-INF\web.xml 文件修改。修改其中的 logDir 和 currentBuildStatusFile 参数。 logDir 是指定 CruiseControl 执行后，为报告生成的日志目录位置，而第二个参数是指定日志状态的文件。默认的 logDir 是 logs ，也就是 cruisecontrl 目录下的 logs ， currentBuildStatusFile 是 status.txt ，这里我们不作修改。在 config.xml 中配置 log 路径到 logs 下即可

7)         project ：一个自带的项目 connectfour ，包含了 src 、 lib 、 test 和 build.xml 。

8)         webapps ： web 应用目录。 CruiseControl 内置了 Jetty 作为 web container ，可以通过 web 方式查看构建结果和手动创建项目

1.3        启动 CruiseControl

1)         启动 CruiseControl

CruiseControl 安装完毕后，在命令行方式，进入 cruisecontrol.bat 所在目录，执行 cruisecontrol.bat 。

2)         控制台输出信息

控制台会输出一大堆的信息，还有一些错误。不要紧，这是由于 CruiseControl 默认的配置是使用 svn 导致的。后面会对此做修改。执行完毕后，程序不会退出，处于等待状态。

如果执行时报端口占用，如：

org.mortbay.util.MultiException[java.net.BindException: Address already in use: JVM_Bind]

可以通过修改 cruisecontrol.bat 文件来修改端口

set EXEC=%JAVA_PATH% %CC_OPTS% -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder -jar "%LAUNCHER%" %* -jmxport 8001 -webport 8089 -rmiport 1099

3)         日志

这时会发现 cruisecontrol 多了一个日志文件 cruisecontrol.log ，文件信息与控制台的信息是一样的。

4)         以 web 方式查看

打开浏览器，访问 http://localhost:8089/ 会看到 CruiseControl 的界面，这里的端口要和 cruisecontrol.bat 中的端口一致。

关闭控制台或 Ctrl+C 退出 CruiseControl ，然后我们进行下一步配置。

1.4        配置

1.4.1         配置 CruiseControl

修改 config.xml ，该文件位于 CruiseControl 安装目录下。

<cruisecontrol>

<project name="HelloWorld">

      <listeners>

            <currentbuildstatuslistener file="logs\${project.name}\status.txt"/>

      </listeners>

      <bootstrappers>

         <currentbuildstatusbootstrapper file="currentbuild.txt" />

      </bootstrappers>

      <modificationset quietperiod="30">

         <ucm stream="HelloWorld_Int" viewpath="M:\ccadm_HelloWorld_int\HelloWorld_vob" contributors="true"/>

      </modificationset>

      <schedule interval="30" >

         <ant antscript="apache-ant-1.6.5\bin\ant.bat" buildfile="F:\ForCruisecontrol\build-HelloWorld.xml" target="cleanbuild"  multiple="5" />

         <ant antscript="apache-ant-1.6.5\bin\ant.bat" buildfile="F:\ForCruisecontrol\build-HelloWorld.xml" target="masterbuild" multiple="1" />

      </schedule>

      <log dir="logs\${project.name}">

         <merge dir="F:\ForCruisecontrol\HelloWorld\test-results"/>

      </log> 

      <publishers>

          <currentbuildstatuspublisher file="currentbuild.txt" />

              <htmlemail mailhost="mail.longtop.com"    returnaddress="cruisecontrol"  skipusers="true"   subjectprefix="[HelloWorld Build Report]"   buildresultsurl="http://172.16.114.205:8080/buildresults/HelloWorld">

                     <!--failure address="[e-mail]" />   

                     <success address="[e-mail]" /-->   

                     <!--map alias="ccadm" address="[e-mail]"/-->

                     <propertiesmapper file="emailmap.txt"/>

                </htmlemail>

              <clearcasebaselinepublisher viewtag        = "ccadm_HelloWorld_int"

                                                          baselineprefix = "HelloWorld_"

                                                          full = "true"

                                                          component      = "HelloWorld_src@\testLocal_pvob"/>

              <onsuccess>

                     <artifactspublisher dir="F:\ForCruisecontrol\HelloWorld\dist"   

                                                        dest="artifacts\${project.name}\"/> 

              </onsuccess>

 

      </publishers>

   </project>

</cruisecontrol>

\docs\main\configxml.html 是 config.xml 的帮助内容，我们可以从这里面找到所有的配置。其中，部分属性说明如下：

<cruisecontrol>

<cruisecontrol> 是配置文件的根元素，它可以拥有一个或多个 <project> 子元素。本例中它拥有一个项目名为 HelloWorld 。

<project>

<project> 元素是一个完整的 build 任务，包括检查配置管理库是否有新的修改，构建项目并发布项目构建结果。它告诉 CruiseControl 构建什么，何时构建，如何构建以及如何发布构建报告。它有一个必需的属性 name 。

<project> 元素的子元素包括 <listeners> ， <bootstrappers> ， <modificationset> ， <schedule> ， <log> ， <publishers> ， <dateformat> 和 <plugin> ，其中 <modificationset> 和 <schedule> 是必需的元素。

 

<listeners>

<listeners> 的子元素 <currentbuildstatuslistener> 记录了当前 build 的状态和最近一次状态改变的时间。

 

<bootstrappers>

<bootstrappers> 元素是启动任务 Plugin 的容器，用于定义构建任务启动前需要执行的任务。常用的 Plugin 包括：
       1. <currentbuildstatusbootstrapper> ，定义一个 CruiseControl 的构建状态信息文件。 CruiseControl 的 Build Result JSP 从该文件读取状态信息并显示在页面上。属性 file 用于指定构建状态文件目录和文件名。
       2. <clearcasebootstrapper> ，用于在项目构建开始前从 ClearCase 服务器上 update 指定的文件。通常可以用于更新项目的构建脚本。属性 viewpath 指定本地工作目录，属性 file 指定需要 update 的文件名，相对于属性 viewpath 指定的目录。

 

<modificationset>

<modificationset> 元素用于告诉 CruiseControl 是否需要构建项目，即配置管理库的代码是否存在更新。监控本地工作目录，如果在下面的目录中发生变化则自动执行下面的构建，没有变化则不再执行下面的构建工作。它拥有三个可选属性 requiremodification 、 quietperiod 和 ignoreFiles 。
       属性 requiremodification 告诉 CruiseControl ，在配置管理库没有代码更新的情况下，是否需要构建。缺省为 "true" ，即没有更新则无须进行构建。

属性 quietperiod 告诉 CruiseControl ，最新一次代码提交后 CruiseControl 需要等待的时间（秒）。用于防止 CruiseControl 在开发人员提交代码时进行项目构建。缺省为 "60" 秒。

在本例中使用 <ucm> 来检查和工作目录相关的代码在 ClearCase 配置管理库是否有更新。 <ucm> 使用 ”cleartool lshistory ” 命令来检查最新更新工作目录和当前代码库的差异。其中 -since 参数后面的时间保存在 <currentbuildstatuslistener> 的文件中，一般为 status.txt 。 <viewpath> 要加上 vob 路径，否则会报 cleartool: Error: Not an object in a vob: "." 错误

 

<schedule>

到目前为止，以上的配置文件内容已经定义了 CruiseControl 构建什么以及何时构建。 <schedule> 元素告诉 CruiseControl 每隔多长时间（秒）启动一次构建任务。它有一个可选的属性 interval ，用于定义以秒为单位的时间间隔。缺省为 "300" 秒。

在本例中，属性 interval 设为 "30" ，这意味着 CruiseControl 每隔 30 秒使用 <modificationset> 定义的任务检查一次代码库。如果设置了定时执行，则 interval 的设置就会忽略。定时执行可以在 <ant> 子元素的 time 设置，格式是 HHmm ，如果 multiple 设置了就不能设置 time 。

<ant> 子元素告诉 CruiseControl 何时或每隔几次运行 Ant 来构建项目。

在本例中， antscript 属性设定 Ant 的路径， buildfile 属性设定构建脚本 build file 的目录。

属性 multiple 告诉 CruiseControl 每隔几次执行一次本 <ant> 任务。

除此之外，还可以指定 Ant 的运行时间（ time 属性）， build file 的 target （ target 属性，不设定则为 build file 的缺省 target ）。

 

<log>

<log> 元素设定 CruiseControl 日志文件的存放目录，并通过 <merge> 子元素指定合并什么样的 XML 文件（构建过程中产生的文件）到 CruiseControl 的日志文件中。

<merge> 子元素的 pattern 属性定义匹配的文件名模式，缺省为 ".xml" ； dir 属性用于指定一个目录，这个目录下所有匹配模式的文件将合并到 CruiseControl 的日志文件中。这个例子合并 junit 产生的日志文件，我们就能在 build 的最终结果看到这些全面的日志

 

<publishers>

<publishers> 元素用于指定构建任务结束后， CruiseControl 如何发布项目构建结果。项目构建结果的发布方式可以是 Email ，网页，复制代码库到指定的目录，或是发布代码库到 FTP 服务器。

在本例中，用到 <currentbuildstatuspublisher> ， <htmlemail> ， <clearcasebaselinepublisher> 和 <artifactspublisher> 这四个 publisher 。
       <currentbuildstatuspublisher> 把下次构建的时间写入指定文件，文件名由 file 属性设定。

<htmlemail> 把构建结果以 HTML 格式通过 Email 发布。缺省情况下， HTML 格式的 Emai 和 CruiseControl Web 应用的构建结果 JSP 页面相同。

<clearcasebaselinepublisher> 在指定得视图上建立 UCM 基线。

<artifactspublisher> 元素把项目构建产品复制到指定的目录， dir 属性定义源目录， dest 定义目标目录的父目录（实际目录还要加上构建时的时间戳，如：父目录 /19890604203828 ）。

其中 <onsuccess> 表示当 build 成功时执行 publish ，如果是失败用 <onfailure>

 

更多的配置项请参见 \docs\main\configxml.html 是 config.xml 的帮助内容，我们可以从这里面找到所有的配置。

1.4.2         配置 ant 的构建文件 build.xml

修改 build.xml ，该文件位于 helloworld 目录下。

1)         注释掉 build.compiler 和 build.compiler.emacs

<!--property name="build.compiler" value="jikes"/-->

    <!--property name="build.compiler.emacs" value="true"/-->

2)         修改 source.dir 为源码路径

<property name="source.dir" value="M:\lisushi_view\2007_demo_vob\demo_SRC\helloWorld\src"/>

3)         修改 clearcase.viewpath 为 view 路径

<property name="clearcase.viewpath" value="M:\lisushi_view"/>

4)         修改 ccdir 为 CruiseControl 安装路径

<property name="ccdir" value="C:\cruisecontrol"/>