Automating builds using CruiseControl and Maven

article by nnarasimha

CruiseControl is a framework for continuous build process. CC in short will help to automate and reproduce builds many times a day. This also runs unit tests and code can be integrated daily. There is also a reporting tool that will give you status of the builds. With scheduling you can either run it every second or at the end of business day.

Continuous Integration by Martin Fowler and Matthew Foemmel.

Lack of proper documentation makes it extremely hard to set this up. After intense searching and trial and error, I was able to set up CC to work with Maven.

If you have already downloaded Maven, then you have all the required plugins like CC, SCM (Source control Management) and CVS bundled along with the core.

To run standalone CC follow the link http://cruisecontrol.sourceforge.net/gettingstarted.html

Setting up Work Area

a. Download CC from http://cruisecontrol.sourceforge.net/index.html either source or binary. If you have downloaded the source follow the given instructions to build the source. The root directory will be the home directory for CC, which will be used later in maven to specify in project.xml.

b. Now we need to create some working directories and configuration file. As an example lets take C:workcruise as our working directory which will be known from now as WORK_DIR.

c. Under WORK_DIR create following sub-directories
· checkout- source code is checked out into this directory
· log ? all logs are written into this directory
· artifacts ? CC puts all the build output files.

d. Let C:projectsj2ee-dbmaint where the source is kept and current modifications is being done be the PROJ_DIR.


Checkout project

a. Manually checkout a project into WORK_DIR/checkout that we will refer to as j2ee-dbmaint. Now your directory structure will be WORK_DIR/checkout/j2ee-dbmaint

b. In maven project.xml file add the following CC properties
· maven.cruisecontrol.home=C:/temp/cruisecontrol-2.4.1
· maven.cruisecontrol.work.dir=C:/work/cruise
· maven.cruisecontrol.checkout.dir=${maven.cruisecontrol.work.dir}/checkout
· maven.cruisecontrol.logs.dir=${maven.cruisecontrol.work.dir}/logs

c. Even though we don?t use the CVS plugin, it is referred by CC, hence we need to define the following properties.
· maven.scm.url=scm:cvs:pserver:<username>:<password>@<server>/<cvsroot>:<module_name>
· maven.scm.tag=v1_1_4
· maven.scm.cvs.module=j2ee-dbmaint

Creating configuration file

a. Next we need to create a delegating script file, which needs to be called by our project build script. But we will bypass this and configure CC to directly invoke the project build script.

d. Create config.xml under WORK_DIR and it should resemble as below. This is a trimmed down version but these are the basic properties we need to get CC running.

<cruisecontrol>
<project name="j2ee-dbmaint" buildafterfailed="true">
<listeners>
<currentbuildstatuslistener file="logs/j2ee-dbmaint/status.txt"/>
</listeners>

<!-- Bootstrappers are run every time the build runs, *before* the modification checks -->
<bootstrappers>
</bootstrappers>

<!-- Defines where cruise looks for changes, to decide whether to run the build -->
<modificationset quietperiod="10">
<cvs localworkingcopy="checkout/j2ee-dbmaint"/>
</modificationset>

<!-- Configures the actual build loop, how often and which build file/target -->
<schedule interval="7200">
<maven mavenscript="C:Maven 1.0.2inmaven.bat"
projectfile="C:workcruisecheckoutj2ee-dbmaintproject.xml"
goal="scm:update-project|clean test|site:deploy"
/>
</schedule>

<!-- directory to write build logs to -->
<log logdir="logs/j2ee-dbmaint"/>

<!-- Publishers are run *after* a build completes -->
<publishers>
</publishers>
</project>
</cruisecontrol>

Build Loop

a. Run CC from your project directory PROJ_DIR as follows
maven cruisecontrol:run

b. To actually kick-off a build, commit changes into CVS from PROJ_DIR. The advantage with CC is that you don?t have to restart if you make changes to your code or the configuration file since it reloads every time a build is being performed. Of course it needs to be committed into your version control.

c. If a build fails then it will keep trying until everything

Report Status

Its very easy to track the status of the builds by receiving emails. Depending on build success or failure emails can be sent out to a specific group of addresses. This is done by adding the <email> element within the <publishers> element.

<email mailhost="SMTP_HOST" returnaddress="cruise@mydomain.com"
buildresultsurl=?http://localhost:8080/cruisecontrol/buildresults/j2ee-dbmaint? skipusers="true" pamwhilebroken="true">
<always address="dev1@mydomain.com"/>
<always address="dev2@mydomain.com"/>
<failure address="failed-builds@mydomain.com"/>
</email>


Resources

[1] http://cruisecontrol.sourceforge.net/gettingstarted.html