搭建你的持续集成服务器 CruiseControl

分类： CruiseControl 2008-01-13 16:19 8923人阅读评论(3) 收藏举报

CruiseControl是CI服务器的老者，诞生已是多年，在许多方面，CruiseControl服务器已经成为持续集成实践的同义词。而现在，CruiseControl已发展成为一个家族式系统，包括CruiseControl.java、CruiseControl.net、 CruiseControl.ruby等适应不同语言环境的实现，其强大的插件和扩展能力也是诸多同类系统无法比你的。而在这里，我只介绍该家族的本家 CruiseControl.java，即CruiseControl。CruiseControl是一个不错的持续集成服务器，不过国内社区的普遍反应是：它的配置太麻烦，无从下手。从本篇文章开始，我将逐步介绍CruiseControl的环境搭建与配置，以及持续集成中的一些实践。我们将从最简单的使用方式（stand-alone）开始，以便您可以快速开始您的持续集成之旅，而不必面对“千奇百怪”的问题。
好！先让我们简单搭建个持续集成服务器再说吧

一、我使用的CruiseControl版本

CruiseControl是一个java开源项目，我将以它最近的一个分支版本来介绍它的使用。CruiseControl最近发布的版本是V2.7.1。这个分支版本就是在V2.7.1基础之上。
这个分支版本包含一个Dashboard，可以方便地看到各项目的构建状态。
这个分支版本当然还支持多个Build Loop，你可以在多个机器上部署独立的Build Loop，从而建立你自己的Build Grid。

二、得到CruiseControl的分支版本

要得到这个分支版本，你可以使用subversion不用任何密码从CruiseControl的Repository中检出。命令如下：
svn checkout https://cruisecontrol.svn.sourceforge.net/svnroot/cruisecontrol/branches/cce/cruisecontrol/

三、构建CruiseControl

0. 你机器上至少要安装有JAVA 1.4，并在环境变量中设置有JAVA_HOME，并把java/bin加入到path中。CruiseControl自带了ANT，所以不用事先安装。

从源代码中构建CruiseControl

       如果从源码中构建CruiseControl，要确保你的机器可以访问互联网。因为构建过程中要检查一些license。另外，最好有SVN 客户端软件，因为在构建时，它会用到javahl。
       在刚刚checkout出来的CruiseControl目录下，有一个批处理文件，名为release.bat。运行这个批处理文件，你会在 target目录下发现一个压缩文件，名这cruisecontrol-bin-2.7.2-dev.zip。将其解压到一个目录，我们这里解压到C盘根目录下。解压后，目录结构如下：

2. 直接使用已构建完成的CruiseControl
如果你不想做这一步，也可以在binaryrelease目录下发现解压后的文件，把它们拷贝到相应的目录下也可以。

四、运行CruiseControl

   CruiseControl可以运行在多种应用服务器中，当然，它自己也捆绑了一个开源应用服务器，那就是Jetty 6。为了尽快建立我们的环境，我们这里暂时使用它自己捆绑的Jetty，快速开始我们的持续集成之旅。
   直接运行CruiseControl目录下的CruiseControl.bat，它会自行启动Jetty6，当从Console中看到它启动完毕后，你就可以在浏览器中访问http://localhost:8080/dashboard，此时你会看到一个名为connectFour的示例项目在 Dashboard上显示了。

Build Dashboard

（如果你足够快的话，你会发现Dashboard 上的小方块是从灰色变成深绿色的。为什么呢？我们以后再说。）
“绿色”表示该项目构建通过。如果要是有多个项目的话，应该看到多个小方块。

点击“Builds” Tab页，就到了 Builds 页。这一页会以列表的方式显示所有的项目。当前只有一个项目，所以在列表中只有一行，如下图所示：
Builds Page
在该页面上点击某个项目时，会打开Build Detail页，显示该项目最近一次Build的信息。页面右侧是该项目所有历史构建信息。你会发现，这时connectFour项目有两个构建历史版本，一个是刚刚构建完成的，另一个是两年前的构建。这些信息是来自于CruiseControl对该项目的日志文件。此时，点击这两个构建结果中的任何一个，都会打开该次构建的Build Detail页面，显示相关的构建历史信息。如下图所示：

CruiseControl的配置文件的确了比较复杂，一方面是因为：它太灵活，太想完成你想达到的任何效果了。另一方面就是：它在文档化方面的确很落后。你只能在用户组中找答案。（不过，这也是学习的一个途径。如果你了解开源的话，你就会习惯于在用户组中找答案啦。）

再了解配置文件之前，让我们先定义一下我们可能会用到的术语。

工作目录（也就是CruiseControl的工作目录）：是指启动CruiseControl的脚本目录。在Stand-alone情况下，就是文件cruisecontrol.bat所在的目录。如果你把它部署到了应用服务器中，那一般就指bin目录了。

       2. Log 目录：就是CruiseControl存储所有构建项目日志信息的目录，默认值为工作目录下名为logs目录。
       3. Projects目录：就是CruiseControl存储所有构建项目源代码的目录，默认值为工作目录下名为projects目录。

一、配置文件及其正确位置

      配置文件包括两个，一个名为config.xml，另一个名为dashboard-config.xml。默认情况下，这两个文件和cruisecontrol.bat在同一下目录下，即工作目录。
     如果在配置文件中，任何路径前面如果没有“/”的话，那就是相对于工作目录的。


      另外，CruiseControl是可以改变他们的位置的，但建议在没有深入了解CruiseControl时，不要试图改变它们，因为我们的目标是让CruiseControl在最短的时间里为你创建价值。

二、Config.xml 文件

<cruisecontrol>
    <project name="connectfour"> －－这里的name应该和你在projects目录下的项目名完全一致。

        <listeners>          －－用于监听项目状态的变化（指building,passed等）
            <currentbuildstatuslistener file="logs/${project.name}/status.txt"/>   －－这里的${project.name}
        </listeners>                                                                                                                 是指“connectfour”

        <bootstrappers>        －－用于CruiseControl从Repository更新代码
            <svnbootstrapper localWorkingCopy="projects/${project.name}" />
        </bootstrappers>

        <modificationset quietperiod="30">      －－用于监听在quietperiod秒内，Repository是否变化
            <svn localWorkingCopy="projects/${project.name}"/>
        </modificationset>

        <schedule interval="300"> －－用于每隔interval秒，CruiseControl去检查并计划一次构建
            <ant anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml"/>
        </schedule>

        <log> －－用于得到并保存log文件。默认情况下，将放在projects/${project.name}的目录下
            <merge dir="projects/${project.name}/target/test-results"/> －－用于将Build中生成的结果合并
        </log>                                                                                                            到log文件中

        <publishers> －－用于将构建的结果（如二进制文件）发布到指定的位置
            <onsuccess> －－决定在构建成功的情况下，发布哪些内容
                <artifactspublisher dest="artifacts/${project.name}" file="projects/${project.name}/target/${project.name}.jar"/>
            </onsuccess>
        </publishers>

    </project>
</cruisecontrol>

三、dashboard-config.xml

<?xml version="1.0" encoding="UTF-8"?>

<!--

/********************************************************************************

这里省略了一些声明 :)

********************************************************************************/

-->

<buildloop

logsdir="" －－这里指定logs目录，一定要与config.xml文件中一致，否则你会有麻烦。
如果为空串，则默认为工作目录下的logs目录。

artifactsdir="" /> －－这里指定artifacts目录，一定要与config.xml文件中一致
如果为空串，则默认为工作目录下的artifacts目录。

<features allowforcebuild=""/> －－是否可以在Dashboard上强制构建(force build)

<trackingtool projectname="" baseurl="" keywords=""/> －－这是用于与Mingle的集成

<subtabs> －－在这里，你可以自己扩展你自己的subtab页，不过要先实现一些接口。

</subtabs>

</dashboard>

四、配置文件中的注意事项

1、如果logs、artifacts和projects目录不存在，在你运行CruiseControl之前，要手工建立它们。
2、确保两个配置文件中的logs/artifacts目录指向同一个目录。因为CruiseControl core会向其中写数据，而Dashboard会从中读数据。

五、小贴士

在Config.xml文件中，有几个元素的概念要先澄清一下(只针对当前示例，严格定义请参见CruiseControl的文档)。

<listeners> 用于监听状态变化，如waiting for build，queued，building。一般不用改变。
<bootstrappers>用于检出代码，CruiseControl有很多种bootstrapper，示例中使用的是SVN。localWorkingCopy属性是指你把代码检出到安装CruiseControl机器的哪个文件目录。
<modificationset>用于监听Repository的变化频率，如果CruiseControl发现代码有变化，而且在quietperiod秒内没有其它用户检入代码（用于保证被构建的版本完整性），CruiseControl才会检出代码。
<schedule >用于指定CruiseControl去检查Repository的时间间隔。并指定使用哪个构建文件。示例中使用的是ant脚本，构建文件是被检出项目的根目录下的build.xml（即在Repository中）。
<log>用于指定CruiseControl把日志放在哪里，把哪些构建结果放在日志中。如果没有指定任何属性，默认为logs目录下的${project.name}目录。
<publishers> 用于在构建结束后，发布哪些消息和文件。CruiseControl有很多插件可以做各种各样的Publishing。例如，在构建成功后，通过http调用指定的页面，也可以给指定的人发邮件。在失败时，播放音乐，通知team。

今天就写到这里，下次我们介绍如何加入一个Project。

好，现在我们已经在自己的机器上建立了一个持续集成服务器，并初步了解它的配置文件。在本文中，我们就要把自己的项目加到其中。做为一个入门示例，我们先要陈述一下假设条件，以便我们快速推进我们的部署过程。

一、准备工作（请确认一下）

1、你的项目代码放在Google Code上面（Google Code用的是SVN ），你的项目名称是yourprojectname，项目的源文件就放在trunk目录下。那么，其svn update的链接如下：http://yourprojectname.googlecode.com/svn/trunk/。CruiseControl只会更新文件，不会修改源代码，所以匿名检出就可以了。

2、你的项目是一个JAVA项目，用ANT进行构建，构建文件名为build.xml，放在项目的根目录上，默认的ant task名为all。确保文件中其中所有路径都是相对于项目根目录的，将其Copy到任何目录下，ant all都可以正确运行。（我们的主要目的是建立环境，使其在今后的开发工作中可以发挥作用，而不是要发现我们构建脚本中错误。）

3、你的CruiseControl工作目录是C:/CruiseControl，方便起见，我们以下将用${CC_HOME}代替。

4、你的logs目录是${CC_HOME}/logs。如果你没有独自改动配置的话，它的位置就如前所述。

5、你的projects目录是${CC_HOME}/projects。如果你没有独自改动配置的话，它的位置就如前所述。

6、你的artifacts目录是${CC_HOME}/artifacts。如果你没有独自改动配置的话，它的位置就如前所述。

二、加入项目

1、手工检出文件：

确保将你的项目代码检出到${CC_HOME}/projects/yourprojectname目录下，即在该目录就是你项目的根目录，可以找到名为build.xml文件。

2、修改配置文件（添加你的项目）

将下面的代码段加入到config.xml文件中，位于<CruiseControl>节点下。

<project name="yourprojectname"> －－这里一定要与你的projects目录下的项目名相同

</listeners>

</bootstrappers>

</modificationset>

</schedule>

<log>

</log>

</onsuccess>

</publishers>

</project>

最终的文件如下：

</listeners>

</bootstrappers>

</modificationset>

</schedule>

<log>

</log>

</onsuccess>

</publishers>

</project>

</listeners>

</bootstrappers>

</modificationset>

</schedule>

<log>

</log>

</onsuccess>

</publishers>

</project>

</cruisecontrol>

三、看一下结果

(1) CruiseControl会自动更新这个配置文件，加载时间一般是在任何一个项目需要检查是否有更新时。

(2) 你会看到这个项目在Dashboard上首先是灰色的方块，因为这个项目还从来没有在CruiseControl上构建过，没有任何历史信息，我们称该项目为"inactive"。

(3) 过一会儿，你会看到一个环形动态图标，表示它在构建中（执行build.xml脚本）。

(4) 当环形动态图标消失时，你会看到它变成红色（如果构建失败的话）或绿色（如果构建成功的话）。

我新加的项目名是vcdstore，现在我的dashboard上有两个项目了。

小贴士：

(1) 目前CruiseControl还不支持首次自动检出代码，所以你要先把项目代码手工检出到本地。

(2) 如果你的SVN使用https方式更新代码，你一定要在命令行方式检出代码，并选择永久接受证书。

(3) CruiseControl这个分支版本不支持在UI上增加项目。

(4) 如果你在config.xml文件中把你的项目删除，却不删除它的日志的话，你在Dashboard上还是可以看到这个项目，此时它被标记为"Discontinued"，表示你可以看到它的历史信息，但CruiseControl不会再构建它了。

下一篇我们将讲述CruiseControl的一些界面信息元素。

现在，我们已经为自己的项目建立了持续集成服务器。让我们来看一下CruiseControl正在对你说些什么。

一、项目的状态

首先CruiseControl把项目分成三类，Discontinued，Inactive，及Active。

如果一个项目是Discontinued，表示CruiseControl可以找到该项目的日志文件，但在配置文件(Config.xml)中并没有该文件。所以CruiseControl不会去构建它，但你可以看到这个项目过去构建的历史信息。如果想把这个项目从CruiseControl中删除，只有把该项目的日志目录删除才行。如果该项目名为"vcdstore"，目录当该是${CruiseContor.Home}/logs /vcdstore。

如果一个项目是Inactive，表示CruiseControl在配置文件(Config.xml)中发现了该项目，但是没有发现关于这个项目的任何历史信息，即在CruiseControl的日志目录中还没有该项目的日志文件，或日志文件被人为删除了。CruiseControl会根据配置信息对这个项目进行检查新版本并进行构建。当第一次构建完成后，CruiseControl就会生成日志，这个项目状态就会转为Active了。

如果一个项目是Active，表示CruiseControl即可以找到该项目的日志文件，又在配置文件（Config.xml）中可以发现它。此时，这个项目可能是构建成功，也可能是构建失败，还可能是构建中。

二、Dashboard

你可以通过 http://localhost:8080/dashboard 访问Dashboard。

Dashboard主要有四个页面，它们分别是Dashboard，Builds，Build Details和Administatiorn。

(1) Dashboard

你可以在Dashboard上看到所有项目的状态，红色方块表示该项目最近一次构建是失败的。绿色方块表示该项目最近一次构建是成功的。灰色方块表示该项目可能是Inactive的，也可能是Discontinued。

当把鼠标放在小方块上时，会显示该项目的主要信息。点击小方块，会进入Build Details页面。

(2) Builds

你可以在Builds页面上以列表的方式看到所有项目的状态，点击每个列表，可以进行Build Details页面。

如果你将ForceBuild配置为true，在列表右侧有一个按钮，你可以强迫该项目进行构建，而不必等到其下一次检查，也不必等到它有版本变化。

(3) Build Details

此页面会列出该项目某次构建的详细信息，包括与上次构建相比有哪些变化，测试结果是什么，详细的日志输出，如果构建成功的话，在配置文件(config.xml)中配置的Artifacts也会在名为Artifiacts的tab页上看到。

右侧的列表是该项目所有的构建列表，点击其中一个构建，你就可以得到该次构建的详细信息。

(4) Administration

该页面你可以看到About和Configuration两个子标签。

在About子标签中，你可以看到CruiseControl所用的环境信息，如CruiseControl的版本号、所用的操作系统和JDK版本等。

在Administration子标签中，你可以看到CruiseControl的Dashboard-config.xml文件内容。在该版本中，还不支持修改，也移除了"Add Project"按钮。

三、CruiseControl Reporting

你也可以通过链接http://localhost:8080/ 来访问CruiseControl的Old Reporting。

点击项目名称，可以看到详细内容。

四、CruiseControl JMX控制台

你也可以通过链接http://localhost:8000/来访问CruiseControl的JMX控制台。

在控制台上点击项目名称（如connectfour），可以修改项目配置，暂停/恢复项目构建等。

小贴士：

(1) 以上的链接均以不修改CruiseControl默认配置为基础。

(2) 后面的文章中，我们会介绍如何通过Build Grid来推展我们的CruiseControl构建能力。

如果您一直跟着这个Thread，那么现在你应该已经可以使用CruiseControl来进行持续集成了。如果你有很多项目需要持续集成的话，可能在同一时刻会有很多项目排队等待构建的现象，以至于使各项目团队无法得到及时的反馈，此时一个集成服务器就不够了。下面我们就来扩展我们的 Build Grid吧。

一、前提条件与假设

根据前面的介绍，你的第一台持续集成服务器已经可以正常运行了。这里列出如下假设，以方便后续描述。

(1) 首台持续集成服务器IP地址为：192.168.1.6，hostname为CI_One。

(2) 在首台持续集成服务器上：

CruiseControl的根目录是：C:/CruiseControl，今后用${CC.HOME}表示。

CruiseControl的Projects目录是：C:/CruiseControl/Proects，今后用${CC.Projects}表示。

CruiseControl的Logs目录是：C:/CruiseControl/Logs，今后用${CC.Logs}表示。

CruiseControl的Artifacts目录是：C:/CruiseControl/Artifacts，今后用${CC.Artifacts}表示。

(3) 你将在IP地址为：192.168.1.8，hostname为CI_Two的机器上部署第二个持续集成服务器。

(4) 把名为CI_One的机器做为主服务器，即把CI_Two上构建的日志(Logs)和结果（Artifacts）放发布到CI_One的${CC.Logs}和${CC.Artifacts}中。

(5) 你将在CI_Two上构建名为CI_TWO_connectFour的项目，它也使用SVN作为项目的SCM。

二、准备工作

(1) 将CI_One上的${CC.Logs}和${CC.Artifacts}设为共享目录，保证CI_Two对这两个目录可写。

(2)可以在CI_Two上，把CI_One的${CC.Logs}和${CC.Artifacts}两个目录分别映射成两个网络驱动器，名字为别为Z:/和Y:/。

(3) 将CI_One上的CruiseControl，整个拷贝到CI_Two上的C盘根目录下，即对于CI_Two来说，CruiseControl的工作目录是C:/CruiseControl。（当然，也可以把一个你编译后生成的CruiseControl拷贝过来。）

(4) 在CI_Two的${CC.Projects}目录下，建立名为CI_TWO_connectFour的目录，把SVN中的源代码checkout到这个目录下，并确保build.xml文件在这个目录下。

三、第二台持续集成服务器的配置工作

以下所有工作全部发生在名为CI_Two这台机器上。

(4) 修改配置文件config.xml，如下所示：

</listeners>

</bootstrappers>

</modificationset>

</schedule>

</log>

</onsuccess>

</publishers>

</project>

</cruisecontrol>

(5) 修改启动脚本

打开CruiseControl.bat文件，找到下面这行代码：

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

将下面这段代码：

-dashboardrul http://192.168.1.6:8080/dashboard

加入到上面的代码后，最后的代码如下：

set EXEC=%JAVA_PATH% %CC_OPTS% -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder -jar "%LAUNCHER%" %* -jmxport 8000 -webport 8080 -rmiport 1099 -dashboardrul http://192.168.1.6:8080/dashboard

保存该文件。

四、运行Build Grid

(1) 运行${CC.Home}中的CruiseControl.bat，启动CI_One上的CruiseControl。

(2) 运行${CC.Home}中的CruiseControl.bat，启动CI_Two上的CruiseControl。

五、访问你的Build Grid

(1) 在任何一台可以访问CI_One的机器上，通过浏览器访问下面的网址http://192.168.1.6:8080/dashboard 来查看你构建的项目。当然，使用hostname也可以。因为CruiseControl内置了一个Jetty应用服务器，版本是6.1。

(2) 你同样可以使用http://CI_One:8080/ 访问CI_One的Old Reporting 页面，用http://CI_Two:8080/访问CI_Two的Old Reporting。不过你会发现，你在CI_Two上配置的项目状态在CI_One的Old Reporting页面都显示为?????。这就是Old Reporting 的局限性。

小贴士：

(1) 要保证所有项目（无论在哪台机器上构建）的项目名都不相同，否则，CruiseControl的DashBoard只会选取其中的一个同名项目，忽略其它的同名项目。

(2) 在CI_Two中启动脚本中，一定要正确填写DashBoardURL参数，确保是CI_One的地址和端口。

(3) 如果项目的log文件比较大，或者构建时使用内存较多，在启动脚本中，可以通过增加JAVA命令行参数，扩大JVM的内存，以免出现OutOfMemory错误。

到此为止，CruiseControl的入门篇就结束了。以后，作为CruiseControl的进阶篇，我还将继续介绍CruiseControl的一些详细配置。

2008年2月16日，CruiseControl发布了新的版本(CC 2.7.2 pre-release)。该版本加入了一些新的特性，特别是在Dashboard部分，并修正了一些Bug。

该版本合并了分支，即https://cruisecontrol.svn.sourceforge.net/svnroot/cruisecontrol/branches/cce/cruisecontrol。也就是说，在前几篇博文中介绍的内容在该版本上都是有效的。

下面简要介绍一下该版本的新增特性，你可以到http://tinyurl.com/2zm9mz下载2.7.2 pre-release。

1. 更新了cc-config文件

2.BuildAgents上更强健的AntBuilder

3. Added SVN Bootstrapper to sample project

4. 在Debian下安装CruiseControl后启动之

5. 支持　ExecBuilder/RakeBuilder

6. 支持　不配置 <modificationset>，以及 requiremodifications="false"

7. 基于SVN Repository版本号的SVNLabelIncrementer

8. 兼容　Microsoft Visual Studio Team FoundationServer 2008 (CC-735)

9. 更新部分文档
　　* 　在Maven and Maven2 builders上加入了"timeout" attributes
　　*　增加了对Rake Builder 的支持文档

10. Dashboard
======================
* build loop 通过HTTP post发送数据给Dashboard
* 显示Build Queue
* 显示暂停状态
* 更新tooltips，显示更全面的Build状态信息
* 显示状态为discontinued的项目
* 创建了dashboard widget API，目前的 "dashboards"tab 和 "builds" tab已经使用新的widget API.
* See build information from zipped log files
* 在Build Detail页面有Force build, RSS & JMX console功能的链接
* 在RSS feed中包括最后的build状态
* Dashboard可以运行于IE6， IE7和Firefox2.0
* 使用相对时间格式
* Installation diagnosis widget
* dashboard上可以显示带单引号的项目名称
* 当项目是inactive时，相关按钮变灰（ "all builds", "all successful builds", "config panel" and "force build"）
* 可以通过命令行参数指定dashboard的位置