This document outlines a project to automate the continuous integration of a software project using CruiseControl. It describes configuring CruiseControl to monitor the project's source code repository for changes, automatically build and test the project on each change, and publish the results. The key steps are to define a CruiseControl configuration file to specify the project details, build schedule, and publishers for notifications and artifacts. The build process is also automated using Ant build scripts. This allows validating and testing the project on each code change to catch issues early and monitor code quality over time.

1. Project Automation
Christian Plessl & Stefan Bleuler
Software Engineering Workshop,
December 5-6, 2005
ETH Zürich, Institut TIK December 5, 2005

2. Project Automation: Outline
reasons methods
tools continuous
integration
Project
Automation
reproducible principles
research and pitfalls
2

3. Why should we automate…
…when doing the same thing multiple times?
Example: in all html files: /home/ftp /home/tikftp
save time
repetition is boring, no learning
do the same thing: make the same mistake in all cases
do it more frequently, e.g., update software
do it on a schedule, e.g., backup
…when doing the same thing once?
Example: plot a figure in matlab
reproducibility: “Do it again but change the labels!”
documentation: “Which results did go into the figure?”
Can you reproduce your results?
3

4. What should we automate?
do not automate things you…
…won’t do again.
…don’t want to remember how you did them.
…like doing multiple times.
typical targets for automation
repetitive shell tasks
building and testing of software
simulation runs and analysis of results
4

5. Automation Languages
plenty of languages
general purpose “scripting” languages (Sh, Perl, Ruby)
general purpose languages (C, Java)
domain specific languages (Make, ant, XSLT, Matlab)
you can do anything with any language, but…
there is no “one size fits all” language
use the right language for each task
use the domain knowledge provided by domain specific
languages
make your job as easy as possible
glue the best tools together, be creative
5

6. Automation of Shell Tasks
examples
rename all welcome.html files to index.html
change all links pointing to /proj/* to point to /home/*
benefits
reduce errors
make functionality available to others
strategies
1. level: use the power of the shell (oneliners)
2. level: use scripts
6

7. The Power of the Shell
example: create a zip file of my source files:
command line: zip archive *.h *.c
GUI:
- run WinZip of similar
- create new archive
- select source directory, add *.c filter, add *.h filter
- close archive and quit WinZip
example: mass replace text in files
find . -name “*.html” -exec perl -spi -e 's/string1/string2/g' {} ;
concise and precise
which options have be be set in GUI?
likely to be valid for a long time (GUIs change a lot)
room for further automation
calling a sequence of scripts from a super-script
create wrappers for frequently used commands
7

8. Scripting Languages
shell scripts (sh, tcsh, ksh)
cumbersome syntax
few libraries, rely on external tools (incompatibilities)
manipulation of results difficult
don’t use them, or only for simple sequences of commands
general purpose script languages (Ruby, Perl, Python)
real programming languages (procedural / object oriented)
extensive libraries
strong text manipulation capabilities
very portable if built-in commands are used
can do anything a shell script can do
glue-logic between tools
can use built-in commands and libraries and external commands
8

9. Scripting Shell Tasks
example
generate PDFs from all ASCII handouts for this workshop
benefits
don’t forget anything
do it triggered by changes
method
Trigger perl make
ASCII
for all subdirectories
if filename ends in .txt redcloth
if filename contains searchstring HTML
make file.pdf
move file.pdf to public_html html2ps
end PS
end distill
end
PDF
9

10. Example: Scripting Shell Tasks
10

11. Example: Shell Task Scripting
use strict;
use File::Find;
use File::Basename;
use File::Spec;
my $path_to_scripts = dirname(__FILE__);
my $makefile = quot;$path_to_scripts/handout_makefilequot;;
my $searchstr = $ARGV[0];
my $outdir = $ARGV[1];
my $abs_outdir = File::Spec->rel2abs($outdir);
my @dir_list = '.'; # we start in the current directory
# find all files and for each call ’wanted’
find({wanted => &wanted, no_chdir => 1}, @dir_list);
sub wanted {
my $name = $File::Find::name;
if (-f $_ && $name =~ m/^(.+).txt$/) { # is a file and name ends in .txt
my $prefix = $1;
if($name =~ m/$searchstr/) {
system(quot;make -f $makefile REDCLOTH=$path_to_scripts/redcloth $prefix.pdfquot;);
system(quot;cp $prefix.pdf $abs_outdirquot;);
}
}
} 11

12. More Power: Domain Specific Languages
general purpose scripting languages can do
everything
domain specific languages can do some things
more efficiently
they incorporate domain knowledge
code is shorter, more expressive
programs more efficient
examples: XSLT, matlab, SQL, …
12

13. Example: Domain Specific Languages
XSLT
XML to XML transformations
declarative, template based
<card type=quot;simplequot;>
<name>John Doe</name>
<email>doe@widget.com</email>
<phone>(202) 456-1414</phone>
</card>
<?xml version=quot;1.0quot;?>
<html xmlns=quot;http://www.w3.org/1999/xhtmlquot;>
<head>
<title>business card</title>
</head>
<body>
<h1>John Doe</h1>
<p>email: <a href=quot;mailto:doe@widget.comquot;>
doe@widget.com</a></p>
<p>phone:(202) 456-1414</p>
</body>
</html>
13

14. Example: Domain Specific Languages
application specific XML XSL stylesheet
<card type=quot;simplequot;> <xsl:stylesheet version=quot;1.0quot;
<name>John Doe</name>
<email>doe@widget.com</email> xmlns:xsl=quot;http://www.w3.org/1999/XSL/Transformquot;
<phone>(202) 456-1414</phone> xmlns=quot;http://www.w3.org/1999/xhtmlquot;>
</card>
<xsl:template match=quot;card[@type='simple']quot;>
<html xmlns=quot;http://www.w3.org/1999/xhtmlquot;>
<title>business card</title>
<body>
XML-to-XML <xsl:apply-templates select=quot;namequot;/>
<xsl:apply-templates select=quot;emailquot;/>
transformation <xsl:apply-templates select=quot;phonequot;/>
</body>
</html>
</xsl:template>
XHTML
<?xml version=quot;1.0quot;?> <xsl:template match=quot;card/namequot;>
<html <h1><xsl:value-of select=quot;text()quot;/></h1>
xmlns=quot;http://www.w3.org/1999/xhtmlquot;> </xsl:template>
<head>
<title>business card</title> <xsl:template match=quot;emailquot;>
</head> <p>email: <a href=quot;mailto:{text()}quot;>
<body> <xsl:value-of select=quot;text()quot;/></a>
<h1>John Doe</h1> </p>
<p>email: </xsl:template>
<a href=quot;mailto:doe@widget.comquot;>
doe@widget.com</a></p> <xsl:template match=quot;phonequot;>
<p>phone:(202) 456-1414</p> <p>phone:<xsl:value-of select=quot;text()quot;/></p>
</body> </xsl:template>
</html> </xsl:stylesheet>
example adapted from http://www.brics.dk/~amoeller/XML/xslt-4.1.html 14

15. Code Generation
basic ideas
DRY principle: keep information in one place only
translate between representations of the same information
simple to change
active vs. passive code generators
passive: generate code once (then modify manually)
active: run each time the input data changes
examples
XML to XML transformations
database and access functions: SQL tables and Java Code
methods
scripts
domain specific languages …
15

16. Example: Code Generation
16

17. Building and Testing Software
basic steps
compile link test
build
strategy
only do what is necessary (modification time)
write down recipe in one place
build tools (make, ant, ...)
benefits
incremental builds
can be triggered by changes => continuous integration
what about IDEs?
can do the same with one click
information distributed, not portable
some IDEs can export build procedure as makefile
17

18. Build Languages
make, ant, cmake, imake, rake
domain knowledge
hierarchy of build targets
build rules (templates e.g. File.java File.class)
dependencies
minimal incremental rebuilds
general purpose or language specific
example ant:
knows about javac, jar, rmic, javah, javadoc, etc.
tasks: archive, coverage, compile, deployment,
execution, logging, scm, test, etc
use for: automate build, test, packaging, deployment
18

19. Example: Build Language
REDCLOTH = redcloth
HTML2PS = html2ps
PS2PDF = distill
%.html : %.txt
$(REDCLOTH) $< > $@
%.ps : %.html
$(HTML2PS) $< > $@
%.pdf : %.ps
$(PS2PDF) $<
%.clean : %.txt
rm -f $*.ps $*.html
19

20. Continuous Integration
core idea: run build and test loop continuously
watch repository for changes
run build and tests
publish status of the build and tests to developers
build is successful if:
- uses latest sources from version control
- is built automatically
- passes all unit tests and functional tests
benefits
detect errors early
monitor code quality over time
prevent integration problems
20

21. Contiuous Integration 2
requires: automated building and testing
use a single repository where anyone can get the current version of
all sources (and all previous versions)
automate the build process so that anyone can use a single
command to build the system from the sources
automate the testing so that you can run a good suite of tests on the
system at any time with a single command
tools
CruiseControl
CruiseControl.NET
Tinderbox
damagecontrol
use established version-control, build and testing
frameworks
21

22. Continuous Integration: outline
22

23. CruiseControl Case Study
idea: automate validation and publishing of the
workshop webpage
basic steps
validate XHTML
validate CSS
convert ASCII handouts to PDF
publish on webserver
main tool: CruiseControl
ideal for java
also other languages possible (as you will see)
23

24. Overview CruiseControl
24

25. Directory Layout
cruisecontrol/ myproj/
cc_builds/ build.xml project ant build file
config.xml cc configuration Makefile
cc-build.xml master build file -> trig. LICENSE
checkouts/ co/myproj/build.xml README
bin/ project-spec. autom. tools
myproj/ checkout of myproj bar.sh
...
build/ foo.pl
logs/ build/ build results
myproj/ prod/ production binaries
status.txt build status for myproj test/ test/debug binaries
log_buildno.xml build/test results for doc/ documentation (non-generated)
artifacts/ buildno src/ sources
spam.java
myproj/ ham.java
buildno/ test/ unit tests and functional tests
build archive vendor/lib 3rd party libraries
sample CruiseControl sample project directory layout
directory layout
25

26. CruiseControl: Configuration (config.xml)
<cruisecontrol>
<project name=quot;tecsw_workshopquot; buildafterfailed=quot;falsequot;>
<modificationset quietperiod=quot;60quot; >
<svn localWorkingCopy=quot;checkout/tecsw_workshopquot;/>
</modificationset>
<schedule interval=quot;120quot; >
<ant buildfile=quot;cc-build.xmlquot; target=quot;buildquot;/>
</schedule>
<listeners>
<currentbuildstatuslistener file=quot;logs/tecsw_workshop/status.txtquot;/>
</listeners>
<publishers>
<artifactspublisher
dir=quot;checkout/tecsw_workshop/buildquot;
dest=quot;artifacts/tecsw_workshopquot;/>
<htmlemail mailhost=quot;smtp.ee.ethz.chquot;
returnaddress=quot;bleuler@tik.ee.ethz.chquot;
buildresultsurl=quot;http://tik8.ee.ethz.ch:8080/cruisecontrol/buildresults/tecsw_workshopquot;
logdir=quot;logs/tecsw_workshopquot;
css=quot;webapps/cruisecontrol/css/cruisecontrol.cssquot;
xsldir=quot;webapps/cruisecontrol/xslquot;>
<always address=quot;bleulerquot;/>
<failure address=quot;plesslquot; reportWhenFixed=quot;truequot; />
</htmlemail>
</publishers>
<log dir=quot;logs/tecsw_workshopquot;>
<merge dir=quot;checkout/tecsw_workshop/build/resultsquot;/>
</log>
</project>
</cruisecontrol>
26

27. HTML validation report generation
build rule in build.xml
triggered whenever a modification to SVN repository occurs
actual report is generated by validate_html.rb Ruby script
validate_html calls W3C HTML validator (remote website)
results are read, interpreted, and XML report is generated
<project name=quot;sssequot; default=quot;allquot; basedir=quot;.quot;>
<property name=quot;tools.dirquot; location=quot;toolsquot;/>
<property name=quot;build.dirquot; location=quot;buildquot;/>
<property name=quot;results.dirquot; location=quot;${build.dir}/resultsquot;/>
<property name=quot;htmlpublish.dirquot; location=quot;${build.dir}/public_htmlquot;/>
<property name=quot;htmlvalidation.dirquot; location=quot;${build.dir}/htmlvalidationquot;/>
<target name=quot;validate_htmlquot; depends=quot;build_webpagequot; >
<echo message = quot;Running the HTML validator on the websitequot; />
<exec executable=quot;${tools.dir}/validate_html.rbquot;
failonerror=quot;truequot; output=quot;${results.dir}/html_validation_results.xmlquot;>
<arg line=quot;${htmlpublish.dir} ${htmlvalidation.dir}quot; />
</exec>
</target>
</project>
27

28. Build Results (log_buildno.xml)
excerpt:
<cruisecontrol>
<modifications> subversion revision
<modification type=quot;svnquot;>
<file action=quot;addedquot;> information
<revision>66</revision>
<filename>/talks/8_releasing_software/release.ppt</filename>
</file>
<date>11/29/2005 13:46:57</date>
<user>kuenzli</user>
<comment><![CDATA[initial slide template]]></comment>
<revision>66</revision>
</modification>
</modifications>
<htmlvalidate>
<passed errors=quot;0quot; report=quot;htmlvalidation/index.htmlquot; HTML validation
file=quot;public_html/index.htmlquot; />
<failed errors=quot;14quot; report=quot;htmlvalidation/ie7/test.htmlquot;
report
file=quot;public_html/ie7/test.htmlquot; />
</htmlvalidate>
</cruisecontrol>
28

29. Publishing Process
all build and test results are
log_buildno.xml stored in a single XML file
UnitTest Commit log Build Coding style HTML valid. XSL stylesheets
XSL XSL XSL XSL XSL generate
reports
reports format
UnitTest Commit log Build Coding style HTML valid. the build and
report report report report report
test results
nicely
HTML Email SMS
various
publisher publisher publisher publishers send
results to
developers
29

30. Failed Build (HTML publisher)
build information
summary
build errors and
warnings
test reports
Subversion revision
logfile comments
HTML and CSS vali-
dation report
We have added this
information for our
case study
30

31. Successfull Build (HTML publisher)
31

32. A Bug has been fixed (Email publisher)
email to all who committed since last successful build
32

33. Simulation Runs and Analysis – An Example
revision for a paper
study comparing algorithms
given
algorithms in binaries and source
synthetic data
some scripts for converting output files (a few broken)
multiple results directories per algorithm
one parameter file per algorithm
figures in the paper
task: do exactly the same for another kind of
synthetic data
problems:
what were the parameter settings for the different runs?
which scripts were used for processing which results?
which results did make it into the final figures?
33

34. Simulation Runs and Analysis II
conclusions
“normal” project
“everything” was there
it was mostly useless
Too many things had been performed manually.
advice
do not underestimate the amount of information in a few
commands entered by hand
automation is the most accurate form of documentation
34

35. Reproducible Research - A Vision
scientific experiments should be reproducible
in computer science they really could be
project.tar.gz
results
README
figures
data/
./do_it_all.pl tables
code/
do_it_all.pl
Can I reproduce your results?
35

36. Wrap up: Principles and Pitfalls of Project
automation
don’t repeat yourself DRY
single source principle
prefer convention over configuration
+ prefer modularity over generalization
choose right granularity (rule of thumb: isolate long running
tasks)
you will always have to adapt small things: reduce barrier for
change
use domain specific tools
trying to solve all possible problems
don’t know when to stop
! re-invent the wheel
36

37. Advice
do not try to automate everything
be familiar with the automation possibilities and judge
yourself
everyone should be intimate with
a scripting language
a build tool (make, ant, etc.)
the most important shell commands
one editor
define a good project layout
remove burden from developer of deciding what files to put where
defined directory layout enable automation, e.g. self-testing
stick to the layout!
exchange code and solutions
37

38. Literature
A. Hunt and D. Thomas, The Pragmatic Programmer, Addison Wesley, 2000
D. Thomas et al., Programming Ruby, Pragmatic Bookshelf,
L. Wall et al., Programming Perl, O’Reilly, 2000
T. Christiansen and N. Torkington, Perl Cookbook, O’Reilly, 1998
M. Clark, Pragmatic Project Automation, Pragmatic Bookshelf, 2004
http://cruisecontrol.sourceforge.net
extensive list of code generators: http://www.codegeneration.net
38