On a recent project I setup CruiseControl (version 2.5) as our
continuous integration build tool. Some folks requested I show them how
I set it up...so what better place than here.
cc
|
|--myproject-config.xml
|
|--myproject-build.xml
|
|--startcc.sh
|
|--artifacts
| |--myproject
|
|--logs
| |--myproject
|
|--checkout
| |--myproject
|
|--webapps
| | (contains the cruise control webapps)
|
|
cc is my
CruiseControl work directory. Call it whatever you want. '
myproject' should
be replaced with your project name. The
artifacts/myproject
folder is where all the results of the build will be written out. The
folder
logs/myproject
is where CruiseControl logs will be written to. These could be code
coverage results, junit reports, etc. The checkout/myproject folder is
where the code for your project gets checked out before a build. Never
develop code from this location. The layout described above is designed
for building multiple projects under CruiseControl.
Here is
myproject-config.xml.
This file contains all of the CruiseControl configuration. It contains
things like
- how often to check the repository for changes
- if there are changes whats the build script to execute
- after a build where to put all the generated artifacts
(like junit reports, etc.)
- should we send email notifications
- ... so on ... you get the idea. Refer to CruiseControl at
SourceForge.
Here is my main
config.xml
which simply includes project specific config.xml files:
<!DOCTYPE cruisecontrol [
<!ENTITY myproject SYSTEM "myproject-config.xml">
]>
<cruisecontrol>
<system>
<configuration>
<threads count="2"/>
</configuration>
</system>
&myproject;
</cruisecontrol>
|
- Nothing much here. Simply including a project specific
config file myproject-config.xml.
- I decided to have two threads for CruiseControl. If you
have multiple projects under CruiseControl management then this
configuration may be of interest to you. This way sepearate project
builds will not be queuing up for threads.
Here is the project specific configruation file that is included above:
myproject-config.xml:
<project name="myproject" buildafterfailed="true">
<plugin name="starteam" classname="net.sourceforge.cruisecontrol.sourcecontrols.StarTeam"/>
<listeners>
<currentbuildstatuslistener file="logs/myproject/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">
<starteam username="thomasm" password="" starteamurl="address:49201/view" folder="dev/myproject" />
</modificationset>
<!-- Configures the actual build loop, how often and which build file/target -->
<schedule interval="1800">
<ant antscript="ant" buildfile="myproject-build.xml" uselogger="true" usedebug="false"/>
</schedule>
<log dir="logs/myproject" encoding="UTF-8">
</log>
<publishers>
<currentbuildstatuspublisher file="logs/myproject/buildstatus.txt"/>
<artifactspublisher dir="checkout/myproject/report" dest="artifacts/myproject"/>
<htmlemail mailhost="mailserver.yourcompany.com"
returnaddress="buildmanager@yourcompany.com"
reportsuccess="fixes"
subjectprefix="myproject Build Results"
buildresultsurl="http://yourcompany.com:12000/cruisecontrol/buildresults/myproject"
skipusers="false" spamwhilebroken="false"
css="webapps/cruisecontrol/css/cruisecontrol.css"
xsldir="webapps/cruisecontrol/xsl"
logdir="logs/myproject">
<success address="devmailinglist@yourcompany.com"/>
<failure address="devmailinglist@yourcompany.com"/>
</htmlemail>
</publishers>
</project>
|
For details on every section please refer to CruiseControl website at
sourceforge.net. Some highlights:
- StarTeam is my repository of choice. CruiseControl comes
with plugins
for various repositories. I have in the past used it with Subversion.
With StarTeam there is an extra step involved in set up. I will come to
this in the end. If you are not using StarTeam then ignore StarTeam
specific notes in this blog.
- In the schedule
section I have scheduled CruiseControl to run every 30
minutes. Check for changes and if there are changes call my delegating
build script myproject-build.xml.
This delegating script is responsible for checking out code and
triggering the actual build for the project.
- In the publishers
section I define what gets copied into the artifacts folder.
Note my project build ant script does most of the work here. The
CruiseControl config above simply copies artifacts produced by it to
the correct folders.
Next here is my delegating script.
<project name="myproject" default="all" basedir="checkout/myproject">
<property name="starteam.lib.dir" value="someplace/starteam/starteam-en-8.0.0-java" />
<path id="classpath">
<fileset dir="${starteam.lib.dir}"/>
</path>
<target name="all">
<taskdef name="stcheckout"
classname="org.apache.tools.ant.taskdefs.optional.starteam.StarTeamCheckout"
classpathref="classpath"/>
<stcheckout URL="starteam_address:49201/view"
username="myuser"
password="mypassword"
rootlocalfolder="checkout/myproject"
rootstarteamfolder="dev/myproject"
createworkingdirs="true"
/>
<ant antfile="build.xml" target="cc-run" />
</target>
</project>
|
- Very straightforward. We first use the StarTeamCheckout
task to checkout changes to the checkout/myproject folder
- Finally we call the projects build script build.xml. In my
case that script does a clean build, produces an ear file, runs the
unit tests, generates junit reports, generates PMD code analyzer
reports and Clover code coverage reports.
Thats it for configuration. I had an additional folder called webapps
which you can copy as-is from the CruiseControl distribution. You can
choose to maintain all of this setup in the CruiseControl install
directory if you choose.
The startcc.sh script which starts CruiseControl is:
somepath/cruisecontrol-bin-2.5/cruisecontrol.sh -cchome somepath/cruisecontrol-bin-2.5
-ccname projects -webport 12000 -jmxport 12001
|
- Since I keep my CruiseControl work area separate from the
distribution i have reference the distributions cruisecontrol.sh to
start CruiseControl.
- -webport is used to start the embedded Jetty server on prot
12000 and -jmxport to set up JMX port.
Finally I encourage you to use some monitoring client application like
this firefox
plugin for CruiseControl. The plugin once configured (set the
URL's in the plugin to the web URL and JMX URL defined previously). The
plugin will show up in the bottom right hand corner of your firefox
browser.
The light is green if the build is good else red. Clicking on the
lights will take you to the CruiseControl home page for your projects.
Here you will see a listing of all configured projects. Clicking on any
will take you the the build results page for your project. You can now
view all of those generated artifacts from here.
StarTeam:
If you are using StarTeam you need to do one additional piece of set
up. Refer to
StarTeam
Setup For CC. I will repeat the steps to illustrate how I did
this. I am using StarTeam 2005 (release 2).
- Download the source distribution of CruiseControl.
- Find starteam80.jar
from your StarTeam client install and copy it as starteam-sdk.jar to
the main/lib
folder in your cruisecontrol source folder.
- Do a build to rebuild.
- Copy the main/dist/cruisecontrol.jar
to your webapps/cruisecontrol/WEB-INF/lib
folder.
- Now you can use my startcc.sh script to start and run
CruiseControl with StarTeam.
- Again like I said before you can choose to keep the webapps folder in
the same folder as the binary distribution. I just choose to keep
everything in my cc folder.
Excellent article. It will save me a lot of time on CC and StarTeam. Thanks.
Reply to this
Brief useful tip
Reply to this
Thanks a lot for this article. It has helped me a lot in dealing with Cruise Control and StarTeam.
Reply to this
Thanks - very useful.
Reply to this
Very useful for understanding how one can create multiple, project-specific config.xml files. Thanks!
Reply to this
Very nice writeup, It helped a lot for me in setting up automated builds.
Reply to this