cruisecontrol的搭建和使用

== cruisecontrol ==
=== cruisecontrol的介绍 ===
{{{
CruiseControl ：简称 CC ，持续集成工具，主要提供了基于版本管理工具 ( 如 CVS、VSS、SVN) 感知变化或每天定时的持续集成，并提供持续集成报告、 Email 、 Jabber 等等方式通知相关负责人，其要求是需要进行日构建的项目已编写好全自动的项目编译脚本 ( 可基于 Maven 或 Ant) 。
}}}
=== cruisecontrol的安装 ===
{{{
1.环境准备
        a.操作系统：以Centos Linux为例，这里在VMware ESXi（VMware workstation也可以）上安装了一个Centos Linux vm，你也可以在物理机上来装一个Centos Linux 机器
    b.配置Java环境
        在家目录下，有一个.bash_profile 文件，在这个文件中配置以下内容：
        export JAVA_HOME=/usr/java/jdk1.5.0_22   ——>根据自身环境配置

        export PATH=$JAVA_HOME/bin:$PATH

        export CLASSPATH=$JAVA_HOME/lib:$CLASSPATH
        也可以在/etc/profile文件中配置。
        注意：有些系统自带jdk，有些没有需要自己安装jdk，本cruisecontrol（2.8.4）试用的jdk版本是jdk1.6，jdk1.7的虽然可以自动化编译测试，但是其Dashboard异常显示，建议jdk1.6版本。
centos自带的jdk目录如下：
/usr/lib/jvm/java-1.6.0-openjdk.x86_64
我的机器java环境配置如下：（/etc/profile）
    export JAVA_HOME=/usr/lib/jvm/java-1.6.0-openjdk.x86_64
    export CLASSPATH=.:/$JAVA_HOME/jre/lib/rt.jar:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
    PATH=$JAVA_HOME/bin:$PATH
    export PATH USER LOGNAME MAIL HOSTNAME HISTSIZE HISTCONTROL
    …
    c.ant环境配置
        同配置java一样，如下：
    export  ANT_HOME=/root/cruisecontrol-bin-2.8.4/apache-ant-1.7.0
    PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH

    注意：配置完这些最好登出，在登录。或者你重启一下host也行。
    d.安装svn
        1.安装
        这里系统自带svn版本控制管理工具，如果没有，就执行以下命令安装：
        [root@localhost ~]# yum install subversion -y
        说明：如果是ubuntu，可以用apt-get命令安装svn。
        2.配置
        利用svnadmin命令创建svn repository，之后，svn有几个重要的配置文件，authz，passwd，svnserver.conf,你可以参考其他文档对其进行配置，然后使用svnserve 命令启动服务即可。
        3.导入项目
        可利用svn import 命令对产品源代码进行导入。

2.安装
    下载安装包：
    cruisecontrol-bin-2.8.4.zip
    安装：
    cruisecontrol的安装很简单，只需要解压即可，不用编译。
如下：
[root@localhost ~]# unzip cruisecontrol-bin-2.8.4.zip
查看一下它的目录：
[root@localhost ~]# cd cruisecontrol-bin-2.8.4
[root@localhost cruisecontrol-bin-2.8.4]# ls
apache-ant-1.7.0  cc.pid      connectfour.ser    cruisecontrol.log    cruisecontrol.log.2  cruisecontrol.log.4  dashboard-config.xml  lib   projects    tp-vgate.ser  vGate.ser
artifacts         config.xml  cruisecontrol.bat  cruisecontrol.log.1  cruisecontrol.log.3  cruisecontrol.sh     etc                   logs  README.txt  velocity.log  webapps
}}}
=== cruisecontrol的目录结构 ===
{{{
projects：存放从源代码仓库中检出来的的项目
logs：存放构建日志和报告
lib：存放cruisecontrol以及插件的库文件
etc：是cruisecontrol内置的jetty服务器的配置文件
webapps：是jetty服务器的应用程序目录，包括CC的管理控制台
apache-ant-1.7.0：CC的内置ANT的配置文件
artifacts（这个目录解压后没有，它是在项目编译成功后生成的）：存放构建成功后的文件
    
几个重要的文件介绍：
config.xml:CC的主要配置文件，包括svn等版本控制管理仓库的检查修改，ANT build周期的配置，    日志的配置以及结果的发布等等。
cruisecontrol.sh:CC的启动脚本，这个是Linux下的，Windows下的是cruisecontrol.bat
dashboard-config.xml:CC 的Web Dashboard配置文件。
}}}
=== cruisecontrol的启动关闭 ===
{{{
依次执行：
[root@localhost ~]# cd cruisecontrol-bin-2.8.4
[root@localhost cruisecontrol-bin-2.8.4]# ./cruisecontrol.sh
然后在浏览器中输入：
http://localhost:8080/cruisecontrol/
或者：
http://ip:8080/cruisecontrol/               ——>注意，ip是你的host的IP地址，请查看host IP地址并替换为你的IP。

如果能看到构建计划页面就说明OK拉。
http://localhost:8080/dashboard/      ——>可查看构建结果。
}}}

=== cruisecontrol的配置 ===
====  config.xml ====
{{{
<?xml version='1.0' encoding='gb2312'?>
<cruisecontrol>
    <project name="connectfour">

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

        <bootstrappers>
            <antbootstrapper anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml" target="clean" />
        </bootstrappers>

        <modificationset quietperiod="30">
            <!-- touch any file in connectfour project to trigger a build -->
            <filesystem folder="projects/${project.name}"/>
        </modificationset>

        <schedule interval="60">
            <ant anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml"/>
        </schedule>

        <log>
            <merge dir="projects/${project.name}/target/test-results"/>
        </log>

        <publishers>
            <onsuccess>
                <artifactspublisher dest="artifacts/${project.name}" file="projects/${project.name}/target/${project.name}.jar"/>
            </onsuccess>
        </publishers>

    </project>

    <project name="vGate">

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

        <bootstrappers>
                <antbootstrapper anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml" target="clean" />
            <svnbootstrapper localWorkingCopy="projects/${project.name}" username="bob" password="qwer1234" />
        </bootstrappers>


        <modificationset quietperiod="60">
            <!-- touch any file in connectfour project to trigger a build
    
            <filesystem folder="projects/${project.name}"/>-->
        <svn localWorkingCopy="projects/${project.name}"
         repositoryLocation="svn://192.168.99.193/${project.name}"
         username="bob" password="qwer1234" />
       </modificationset>

        <schedule interval="60">
            <ant anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml"  target="all" uselogger="true" usedebug="true" />
            <!-- time="1120"-->
        </schedule>

        <log>
            <!--<merge dir="projects/${project.name}" />-->
     </log>

        <publishers>
            <onsuccess>
                <artifactspublisher dest="artifacts/${project.name}" file="projects/${project.name}/target/${project.name}" />
            </onsuccess>
        </publishers>

    </project>

</cruisecontrol>

说明：
这是一个xml文件，相关元素介绍如下：
<cruisecontrol></cruisecontrol>：配置文件的根节点，可以看做是其他元素的容器。
<project></project>:基本的工作单元，包括source code的检查，build，发布结果等，它有一个name属性，用来配置你的工程名称，这个名称必须唯一，不能和其他工程重名。
例如：
<project name=“vGate”>
    …
</project>

<listeners></listeners>:用于监听项目状态的变化

<bootstrappers></bootstrappers>:用于CC从repository更新代码。这里使用了svnbootstrapper来更新版本库
<modificationset> </modificationset>:轮训检查repository的变化，默认时间是60s,你也可以自定义：
<modificationset interval=“300”>
    …
</modificationset>
用于在构建之前，检查repository的变化，如果有变化就更新。

<schedule></schedule>:用于每隔interval秒，CC去检查并计划构建一次工程。例如：
    <schedule interval="60">
            <!-- time="1120"-->
            </schedule>
    说明：其中ant是用于构建的工具，如果想定时构建，只要在ant 的time属性里制定就可以啦，格式是：HHmm，例如：
                 <ant anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml"  target="all" uselogger="true" usedebug="true" time=“1120”/>,表示每天的11：20开始build。


<log></log>:用于保存构建过程中产生的l日志。
<publishers></publishers>:用于将构建的结果发布到制定的位置。
    例如：
        <publishers>
            <onsuccess>
                <artifactspublisher dest="artifacts/${project.name}" file="projects/${project.name}/target/${project.name}" />
            </onsuccess>
        </publishers>

总体配置说明：
    1.首先必须在build之前进行repository检查更新。
    2.设置schedule
    3.保存日志
    4.发布结果


编辑dashboard-config.xml文件
先来看看我的配置文件：

<dashboard>
     <buildloop
        logsdir=""
              artifactsdir="" />
    <features allowforcebuild="true"/>
    <trackingtool projectname="" baseurl="" keywords=""/>
     <subtabs>
        <subtab class="net.sourceforge.cruisecontrol.dashboard.widgets.ErrorsAndWarningsMessagesWidget" />
    </subtabs>
</dashboard>
说明：
在这个文件中，我们可以配置用户是否可以在web页面上进行强制build，也即是强制构建，只要设置下面这一行即可，其他不动：
<features allowforcebuild=“t"/>改为 <features allowforcebuild=“true”/>，如果你不想让别人随意在界面上触发build，你就不用设置这个文件，保持默认即可。
4).在首次启动自动化build之前，你应该手动checkout 一份工程到projects目录下。

}}}
====  build.xml ====
{{{
编辑build.xml文件
 这个文件是ant 用来构建我们的工程的脚本文件。
示例如下：
<project name="vGate" default="all" basedir=".">
    <property name="svn_repositery_dir" value="file:///data/svn/TopSec" />
    <property name="svn_local_dir" value="/root/cruisecontrol-bin-2.8.4/projects" />
    
    <target name="all" depends="clean, compile"/>
   
    <target name="clean">
        <delete dir="target" quiet="true" />
    </target>


    <target name="compile">
            <mkdir dir="target" />
        <exec executable="/bin/bash" dir="${svn_local_dir}/vGate" failonerror="true">
        <arg value="${svn_local_dir}/vGate/build.sh" />
    </exec>
    </target>

</project>

说明：
<property> 可以用来预先设置一些后边要用的常用路径以及其他常用属性值
<target></target> name 是构建的最开始的目标，通过depends设置构建它市的依赖目标，而且是先构建依赖目标，最后构建all。
 可以利用target来定制我们要构建哪写事情，包括清除旧的目标，编译，打包，测试等等。
在target元素里边，我们可以使用mkdir创建文件夹，classpath加载classes文件，jar包文件；使用javac进行编译；使用junit进行单元测试；使用jar来打包所有的编译结果文件等等。
}}}

=== 项目构建状态介绍 ===
{{{
项目有三种状态：
Discontinued：表示CruiseControl可以找到该项目的日志文件，但在config.xml中并没有配置该项目，这种情况下CruiseControl不会去构建它。如果jdk版本不对，或者说CC运行有异常，也可能显示为Discontinued.

Inactive：表示在config.xml中配置了该项目，但是没有发现关于这个项目的Log信息，即在CruiseControl的日志目录中还没有该项目的日志文件，或日志文件被人为删除了。CruiseControl会根据配置信息对这个项目进行检查新版本并进行构建。

Active：表示CruiseControl即可以找到该项目的日志文件，又在config.xml中可以发现它。此时，这个项目可能是构建成功，也可能是构建失败，还可能是构建中。
}}}
=== 可能会遇到的问题 ===
{{{
1).dashboard页面一直显示工程为Discontinued
    如果检查config.xml文件没有问题，logs下的工程日志也没有问题，就检查jdk的版本，CC2.8.4适用于jdk1.6的版本。

2).不能自动构建，或者无法构建
        请检查config.xml文件，看看svn是否配置正确，svn server是否异常，可以手动svn checkout检查，如果没有问题，检查schedule的配置。
3).能构建成功，但是无法去artifacts页面下载结果文件，发生异常。
        还是config.xml文件的问题，仔细检查artifacts的配置,如果没有问题就检查工程的build.xml文件，看看是不是build.xml里地结果输出有问题。
4).cruisecontrol无法启动问题
首先看看是否是执行权限的问题，其次查看config.xml文件，看看是否有重名的工程配置，或是哪个标签写错了。
5).设置了repository定时构建，但是却一直构建，应该是只有变化的时候才构建。
               <!-- touch any file in connectfour project to trigger a build -->
                <filesystem folder=“projects/${project.name}"/>
注意这句话，它的意思是只要工程目录下有变化就构建，所以你把它删掉，并且最好把每次编译留下来的目标文件删除。
例如：
    <bootstrappers>
                <antbootstrapper anthome="apache-ant-1.7.0" buildfile="projects/${project.name}/build.xml"     target="clean" />
            <svnbootstrapper localWorkingCopy="projects/${project.name}" username="bob"             password="qwer1234" />
        </bootstrappers>
}}}