Table of Contents
This chapter shows how to use QuickBuild by going through a couple of typical use cases. All use cases are using CVS as sample repository. You can also use other type of repository here. Configurations used in these use cases resides under configuration root.live-samples which will be available after you've installed QuickBuild. You need to edit basic settings of the root configuration, and set value for variable ant, cvs, and maven according to your environment. These variables will be referenced in child configurations.
From the dashboard, trigger the configuration root.live-samples.usecase1 , the Editing manual trigger settings page will be displayed. For property Build necessary condition, choose menu item Force build from the drop down menu. This will force a build even there are no changes in CVS repository since last build. Click on OK, and the build should be kicked out and run. After some time, refresh the dashboard page; you'll see the build has finished. If all things go well, this should be a successful build. Click on status icon of the newly generated build, the build log will be displayed. In case the build cannot be generated, you can click on status icon of the configuration, and examine what has happened in the configuration log.
You now have successfully run the first build. Let's examine some important aspects for this configuration.
Basic settings
This page shows some basic settings of the configuration. You can set working directory and publish directory for this configuration. Working directory is used to store stuffs specific to current configuration, for example, configuration logs. In this working directory, a directory named checkouts will be created to hold stuffs checked out from configured repositories. In the configuration's publish directory, a directory named builds will be created to hold generated builds, including build logs, published artifacts, etc. If these two directories are set as empty value, they will inherit settings from parent configuration. If you specify a relative path, it is assumed that they are relative to the parent's working or publish directory.
Repositories
Create the CVS repository in this page. Pay particular attention to the CVS executable path property which we assign it with the value ${var["pathToAnt"]} here. The expression embedded in ${...} is OGNL expression. Almost all text properties in QuickBuild can embed OGNL expressions as long as they are surrounded by ${...}. Root of the OGNL expression is always current configuration object. Here we are referring to var property of the configuration object. For properties that can be used in your OGNL expression, please refer to OGNL reference section.
Multiple repositories can be defined. Particularly, for the newly created repository, if you choose a name that is the same as another repository defined in ancestor configurations, newly created repository will override previously defined one. This is also true for builders and steps. So you can define common objects in ancestor configurations, and define particular objects specific to particular child configurations in descendent configurations. In this way, your life of configuring new builds is made simple.
Builders
Create the Ant builder in this page. Here again we use OGNL expressions in Path to Ant executable and Build properties. Take a look at Build properties, we passed several properties to Ant. Among them, buildVersion is used to pass in current build's version; artifactsDir is used to pass in the directory path to which your build results should be copied. This directory is a sub directory of current build's publish directory, and is named as artifacts. Current build's publish directory is a sub directory named by its version under current configuration's publish directory. junitHtmlReportDir is used to pass in directory where you should store your JUNIT html reports. cloverHtmlReportDir is used to pass in directory where you should store your Clover html reports. Of course you can choose property names other than artifactsDir or buildVersion, as long as you refer to these property names in your Ant build script file.
Multiple builders can be defined. Particularly, for the newly created builder, if you choose a name that is the same as another builder defined in ancestor configurations, newly created builder will override previously defined one.
Let's take a look at what should be done in your Ant build
script file. After you have successfully run the build, change
to directory <QuickBuild installation
directory>\working\root\live-samples\usecase1\checkouts
,
and you'll find checked out stuffs from the configured CVS
repository. Change to directory
sample1\build
, and open file
build.xml
; pay attention to the target
distribute. This target creates
distribution file under the directory denoted by property
artifactsDir. Also in target
test, we generate JUNIT html report into
the directory denoted by property
junitHtmlReportDir; in target
cloverreport, we generate Clover coverage
report into the directory denoted by property
cloverHtmlReportDir. In this way, we can
access build results, JUNIT html report, and Clover html report
from QuickBuild's web interface.
![]() | Note |
---|---|
It is not a MUST that you should create build results into directory denoted by artifactsDir, actually, you can put them into any directory. However, these build results will not be able to be shown in the web interface, unless you use the publish step to publish them, which will create soft links in current build's artifacts directory to these build results. |
![]() | Note |
---|---|
Clover html report will only be generated if you have installed Clover. |
Notifiers
Create desired notifiers in this page. Here we defined an Email notifier. This notifier will be referred to when define the notification step, which is used to send failure build notification to users who has checked in since last successful build. Message title and body for this notifier can be customized through using Velocity template. Notification sent out using this notifier will contain links to affecting configuration, build, build log, revision log, and also several lines arrounding the error line inside the build log.
![]() | Note |
---|---|
You can define your notifiers in a high level configuration, so that they can be used by every descendent configuration without need of re-definition. |
Steps
Create desired steps in this page. Here we've defined four steps, check out from cvs, build with ant, create label for successful builds, send notification for failed builds and default, respectively. Pay particular attention to the default one. Actually, When the configuration got running, QuickBuild will only locate and execute the default step (will look for this step in ancestor configurations if not found in current configuration. The same is true of other steps). As you may have noticed, the default step is a serial composite step that will trigger other three steps one by one.
Login mappings
This page is used to map repository logins to QuickBuild users. As you see in steps definition, upon a failed build, the send notification for failed builds step will collect CVS logins who has checked codes into CVS repository since last successful build, and send notifications to them. Before send this notification, these logins should be mapped to corresponding QuickBuild users in order to get contact information such as Emails, MSN messenger accounts, etc. When define repositories, you can refer to these login mappings, so that logins in those repositories can be resolved to correct users in QuickBuild system.
![]() | Note |
---|---|
You can define your login mapping objects in a high level configuration, so that they can be used by every descendent configuration without need of re-definition. |
Child configurations
Create child configurations under current configuration. Currently it is the only place to create, delete or move configurations.