Chapter 8. Use cases

Table of Contents

Working with your first build
Working with Maven
Working with build promotion
Sharing working directories
Sharing build versions
Using date and iteration as part of build version
Managing major, minor, and iteration part of a version string
Specifying label to build against
Updating information of many projects
Working with build queues
Working with public configurations
Building multi-platform products
Working with parallel builds
Working with project dependencies
Performing automation/smoking tests on a machine other than build machine

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.

Working with your first build

Check out code from CVS, build them with Ant, and tag the source when build is successful. Also upon a failure build, notification should be sent to users who have checked in codes recently.

  1. 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.

  2. 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]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]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]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]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.