# LuntBuild - Build Automation and Management

## User guide

Robin Shine

## Version 1.1

### Table of contents

Chapter 1 - Introduction
Chapter 2 - Install and run!
Chapter 3 - Home level pages
Chapter 4 - Project level pages
Chapter 5 - Schedule level pages
Chapter 6 - View level pages
Chapter 7 - Writing your ant build file
Chapter 8 - Write ant build file to wrapper existing makefile or build script
Chapter 9 - Use luntbuild remoting API
Chapter 10 - Build problem diagnostic

### Chapter 1 - Introduction

Luntbuild is a build automation and management tool based on the popular apache ant. With luntbuild,
Daily build, or furthur, continuous integration can be easily achieved. Daily build or continuous integration is considered a best pratice during software development. Refer to the following articles to learn the benefits of continuous build if you are not familiar
with that:
http://www.martinfowler.com/articles/continuousIntegration.html
http://www.joelonsoftware.com/articles/fog0000000023.html

Roughly, luntbuild works in the following way:
1. Get source code from a version control system based on schedule.
2. Set a label on current source code based on current build version
3. Run a ant build script in the source tree
4. Publish the build log and build artifacts

Build configuration, build monitoring, and build artifacts accessing are all done through a web interface. By this way, your development team and testing team can have a central build information access area. SCM members can configure and monitoring builds. Developers can download latest builds for integration. And testers can download designated builds to perform test, etc. All from one place.

### Chapter 2 - Install and run!

NOTE: this procedure is intended for a clean installation, for upgrades, please refer to the release
notes.
1. Download source or binary distribution from http://www.sf.net/projects/luntbuild/
2. Jump to step 6 if you've downloaded the binary distribution. Otherwise, continue here to compile the source distribution
3. Make sure you have jdk1.4 or jdk1.5 installed. Access http://java.sun.com/ for jdk dowloads if you have not them installed.
4. Extract the source distribution into a directory, suppose "/luntbuild-src". Change to directory "/luntbuild-src/build" directory. Run build.bat on windows platform, or run "sh build.sh" on unix-like platform or linux platform.
NOTE: starteam adaptor will not get built by default. If you want to get starteam adaptor built, you need to put starteam SDK jar file(starteam60.jar for starteam 6.0, normally shipps with a starteam client installation) and put it into "/luntbuild-src/lib" directory before build the source.
5. After build finished goto /luntbuild-src/distribute directory, you will get the binary distribution.
6. Extract the binary distribution to a directory, suppose "/luntbuild".
7. Make sure you have tomcat4 or tomcat5 installed. Access http://jakarta.apache.org/tomcat/index.html for tomcat download if you have not them installed. Suppose tomcat installed in directory "/tomcat", and suppose you access tomcat at http://build-server.foobar.com
NOTE: On windows platform, you should not start tomcat in NT service mode, it need to be run foreground.
8 Copy /luntbuild/web/luntbuild.war to /tomcat/webapps/. Start tomcat and luntbuild.war should be automatically extracted as luntbuild/web/luntbuild/.
9. Edit the file /tomcat/webapps/luntbuild/WEB-INFO/web.xml, Change value of parameter "installDir" to the installation directory for luntbuild, that is /luntbuild here.
NOTE: On unix-like platform, please make sure the tomcat process have full read/write access to the luntbuild installation directory
10. Based on your version control system, install proper version control system client as demonstrated below:
1) If you are using visual source safe
You should install visual source safe 6.0 software in your build machine. You can download from http://download.microsoft.com.
2) If you are using cvs
You should install proper cvs client based on your platform, you can download from http://www.cvshome.org or http://www.cvsnt.org if you are using windows platform. Make sure the cvs executable is on the system path
3) If you are using subversion
Subversion client software should be installed in your build machine, and the svn executable should be on the system path. You can download subversion at http://subversion.tigris.org
4) If you are using starteam
Support for starteam needs the StarTeam API which is only available to licensed users of StarTeam. You must have starteam-sdk.jar(or starteam60.jar for starteam6.0) put into /tomcat/webapps/luntbuild/WEB-INFO/lib. Normally this jar file will be avaiable as one of the runtime file after you install starteam client software. Please access http://www.borland.com for any licensing information.
IMPORTANT NOTE: For windows platform, the above step is not sufficient, you will need to have a full installation of starteam SDK runtime(which will install some runtime dlls and put them into the windows system path). Normally this is part of starteam client installation.
5) If you are using perforce
You should have perforce client installed in the build machine, and make sure the p4 command line executable exists in the system path. Contact http://www.perforce.com for any licensing information.
6) If you are using base clearcase or clearcase UCM
You should have clearcase client installed in the build machine, and make sure the cleartool command line executable exists in the system path. Also you should make sure the account to run tomcat should be able to access your clearcase server and can make snapshot views.
11. Restart tomcat, open the web browser, navigate to http://build-server.foobar.com/luntbuild/, and you will get to the luntbuild page. (The first web access for luntbuild will cost some seconds, please wait for some time)

### Chapter 3 - Home level pages

Luntbuild will welcome you with this first page:
Figure 3.1

On the top area of this page, there is a "hierarchy navigation" area, this will navigate you through different level of hierarchies in this system. For example, when you are in "project" level(as denoted below), You can change back to "Home" hierarchy by clicking "Home" link in the hierarchy navigation area.
Figure 3.2
There are five tabs at "Home" level, respectively "builds", "projects", "schedules", "users" and "properties".

1. builds tab
Figure3.1 gives a snapshot of the builds tab. This page shows a gross information of all build schedules configured in the system. Luntbuild comes with some pre-configured projects which you can delete them laterly. The "project" field denotes which project this build schedule belongs. The "view" field denotes which view this build schedule belongs. The "schedule" field denotes which schedule this build schedule uses. The "build strategy" field denotes the build strategy used for this schedule. The notion of "project", "view", "schedule" and "build strategy" will be explained in later sections. The "Lastest build" field denotes the most recent build instance for this build schedule. And the last field denotes all history build instances under this build schedule. There is a search link at left area of this page, you can follow this link to find particular builds, and you can perform some operations upon these found builds, such as delete builds.

2. projects tab
This page shows all projects currently configured in the system. A project can be created by inputing the version control system information for this project. After a project has been created, you can create one or more views under this project. Generally a project can be seen as a category of products using the same version control system, and a view can be seen as special version of product attached to different branches or labels in the version control system, such as maintenence view for old codes, development view for all latest codes, or some bugfix view.
3. schedules tab
By clicking the "schedules" tab, you can view all configured schedules in the system, and can create new schedule and delete existing schedule in the system. Luntbuild uses an open source project http://www.opensymphony.com/quartz/ for its scheduling system. There are three type of triggers for you to select when creating a new schedule, respecitvely "manual", "org.quartz.SimpleTrigger", and "org.quartz.CronTrigger". Schedule using manual trigger can only be trigged manually. "org.quartz.SimpleTrigger" can be used to configure a schedule which repeats at a given interval. And "org.quartz.CronTrigger" can be used to configure a schedule behaves like a unix cron job.
Schedules are not only used to perform builds non-interactively, but can also be seen as build categories. Builds can be moved between these categories as you wish. For example, you can create a manual schedule named by "release builds", attach it to proper views. And later you can promote particular "nightly" builds into "release builds" category. By this way, you can keep track of all released builds. Of course, builds can also be manually triggered in the "release builds" category.
4. users tab
This feature has not been accomplished yet. In the future, user will need to login the system, and administrator can authorize different user with different access rights for different projects, views, etc.
5. properties tab
Properties listed here are applied to all projects configured in the system, some of the properties such as "Command to run ant" and "Environment file" can be overrided by view specific properties. Details of these properties are explained here:
1) "Url to access luntbuild servlet"
The servlet url should be specified correctly here in order to construct urls used in the notification email correct. Normally this value should be http://<server>:<port>/luntbuild/app, where <server> stands for your build server name or ip address, and <port> stands for the port number you used to access luntbuild. If this property is left empty, luntbuild will default this value to be "http://<server_ip>:8080/luntbuild/app", where <server_ip> stands for the actual ip address of the build server.
2) "Command to run ant"
This property is optional. By using this property, you can set the default jdk, jvm options, ant, ant options for all projects in the system. For example, you can input:
/j2sdk1.4.2_04/bin/java -classpath /apache-ant-1.6.1/lib/ant-launcher.jar -Dant.home=/apache-ant-1.6.1 org.apache.tools.ant.launch.Launcher -verbose
By this way, all your projects will be built with jdk1.4 and ant1.6 if not individually specified in the view settings, and verbose information about the build process will be written to log which may helps diagnostic some build problem. NOTE: you should embrace paths with white spaces in quote for this property, for example:
"C:\program files\java\jdk1.5\bin\java" -classpath c:\apache-ant-1.6.1\lib\ant-launcher.jar -Dant.home=c:\apache-ant-1.6.1 org.apache.tools.ant.launch.Launcher
NOTE: for ant options, you should not specify the option "-buildfile" and "-logfile" which will be used by luntbuild. Other options are all allowed.
3) "Environmen file"
This property is optional. By specifying a environment file, you can set some OS specific environment variables before building every project in this system. Environment variables should be specified in this file with the "name = value" format, just like define a java property file. If you specify the environment file, it should be found in the checkouted source tree for every view and every project(except specified in view specific settings). The path for the environment file is relative to the working directory for related view. For example if you input: testcvs/build/env.properties. And suppose we have configured a project "testcvs", and under this project, we configured a view "development" with module "testcvs". When building this view, luntbuild will first checkout module "testcvs" into the working directory of this view, then it will try to read the environment variables from file <view_working_directory>/testcvs/build/env.properties. If it does not exist, the build will fails.
4) "Working directory"
This property is optional. Luntbuild have a working directory which are used to hold checkouted source codes from version control system, and performs builds from there. Each view have a view-specific sub-directory under the working directory, that is, view working directory. By default, luntbuild point working directory to the "working" sub-directory under the luntbuild installation directory. By specifying this property as a absolute directory path in the build server, you can change this working directory.
5) "Publish directory"
This property is optional. Luntbuild have a publish directory which are used to hold builded results and artifacts. Each build have a build-specific sub-directory under the publish directory, that is, build publish directory. By default, luntbuild point publish directory to the "publish" sub-directory under the luntbuild installation directory. By specifying this property as a absolute directory path in the build server, you can change this publish directory. NOTE: Capacity of publish directory should be large enough.

### Chapter 4 - Project level pages

The project level shows detail information about a particular project. There are two tabs in this level: "basic" and "views".
1. basic tab
From this page, you can edit some basic informations for current project, such as name, description, and version control system etc. Currently luntbuild supports the following version control systems:
1) cvs
Proper cvs client should be installed in your build machine, you can download from
http://www.cvshome.org or http://www.cvsnt.org if you are using windows platform. Make sure the cvs executable is
on the system path. Properties of this version control system is straitforward as described in the configuration page.
NOTE: you'd better keep time at the build server sync with the cvs server in order to let build server detect repository changes on cvs server more accurately. Also all times recorded in the revision log are in UTC time format instead of local time format.
2) visual sourcesafe
visual source safe 6.0 software should be installed in your build machine, you can download from http://download.microsoft.com. Properties of this version control system is straitforward as described in the configuration page. We need to emphasize the "datetime format" property here, because it is essensial when determine the modifications since last build. Luntbuild will default it to "M/dd/yy;h:mm:ssa" if it is left empty. However, this default value is only proper when you are using english locale. For other locales, please follow this instruction to determine the format:
Open visual sourcesafe at your build machine, select an existing vss database and choose to view one of the project with files in it, there will be a list of files shown with several fields including the "Date-Time" field. You should drawn the "datetime format" property from value indicated by this field. For example, if one of the value of this field is "04-07-18 20:19", the "datetime format" property can be "yy-MM-dd;HH:mm". The semicolon between date and time format should exist. Of course, you are encouraged to specify the property as "yy-MM-dd;HH:mm:ss" to add the accuracy. Take another example, if the value shown at sourcesafe is "7/18/04 8:19p", the "datetime format" can be "M/dd/yy;h:mma". Of course, "M/dd/yy;h:mm:ssa" will be better to increase the accuracy in this case. The following is a list of format character meanings copied from JDK document:

character | Meaning | Example
y | Year | 1996 ; 96
M | Month in year | July ; Jul ; 07
d | Day in month | 10
a | Am/pm marker | p
H | Hour in day (0-23) | 0
h | Hour in am/pm (1-12) | 12
m | Minute in hour | 30
s | Second in minute | 55

For detail informations about the format string, please refer to http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html
NOTE: In order to keep history command of sourcesafe accurate, time setting of all developer workstation, and the build server should keep in sync.
3) subversion
subversion client software should be installed in your build machine, and the svn executable should be on the system path. You can download subversion at http://subversion.tigris.org, Some important properties of this version control system is described as below:
i) repository url base
This property is used as the base part for the subversion url of this project. Definitions such as modules, directory for branches, or directory for tags are relative to this base url. For example, if you input "svn://localhost" for this property, and you define a module "testsvn" or "/testsvn" with empty label and branch for some view under this project. The actual url for this module will both be "svn://localhost/testsvn". However if label or branch for a module is not empty, url for that module will be calculated differently as described in chapter6/section2.
ii) directory for branches, and directory for tags
Subversion suggests to define seperate branches and tags directory to store the branches and tags as a best practice. Luntbuild utilizes this best practice very well. You can define your own directory for branches or tags here, or luntbuild will choose "branches" and "tags" as the default value for these two property if they are empty. This directory definition is relative to the base url define above. Luntbuild will use these information to calculate actual url for modules with non-empty branch or label. Also luntbuild will use this information to perform the label action for a build. Please refer to chapter6/section2 for details.
NOTE: you'd better keep time at the build server sync with the subversion server in order to let build server detect repository changes on subversion server more accurately.
4) starteam
Support for starteam needs the StarTeam API which is only available to licensed users of StarTeam. You must have starteam-sdk.jar(or starteam60.jar for starteam6.0) put into /tomcat/webapps/luntbuild/WEB-INFO/lib. Normally this jar file will be avaiable as one of the runtime file after you install starteam client software. Please access http://www.borland.com for any licensing information.
NOTE: you'd better keep time at the build server sync with the starteam server in order to let build server detect repository changes on starteam server more accurately.
5) perforce
Perforce client is need to be installed on your build machine, and the command line executable should be in the system path. Please access http://www.perforce.com for any licensing information.
NOTE: you'd better keep time at the build server sync with the perforce server in order to let build server detect repository changes on perforce server more accurately.
6) base clearcase
You should configure the property "Clearcase view stgloc name". Luntbuild will create necessary clearcase view automatically and this property tells the -stgloc option(view storage location) when creating that view. This can be overrided by specifying "Explicit path for view storage" property at view level which will used -vws option instead of -stgloc.
NOTE: you'd better keep time at the build server sync with the clearcase server in order to let build server detect repository changes on clearcase server more accurately.
7) clearcase UCM
Besides the "Clearcase view stgloc name" as described above, you should also specify the property "Project VOB tag". All views under this project will use this specified project vob.
NOTE: you'd better keep time at the build server sync with the clearcase server in order to let build server detect repository changes on clearcase server more accurately.
8) <composite vcs>
This is not a real vcs, instead, it stands for a way to comprise one or more of the above version control systems together to build. When a project is configured with a <composite vcs>, all its views become composite views which can include several basic views. When perform build for such composite view, all repository contents of its included basic views will be checked out to its working directory. For example, you may have a project with its client module resides in a cvs repository, and server module resides in a vss repository. To configure build for such project, you can following these steps:
i) create a normal cvs project, say "cvs_project", and under this project, create a view, say "client", and configure this view to checkout client module.
ii) create a normal vss project, say "vss_project", and under this project, create a view, say "server", and configure this view to checkout server module.
iii) create a project with the <composite vcs> setting, say "myproject", and under this project, create a view, say "myview", and configure this view to include the previously created "client" and "server" view. In this way, contents of client and server module will be checked out to view working directory of "myview" when perform build.
This approach will also applicable for projects whose modules resides on different repositories of the same vcs type. For example, you may have a project with client module resides on a cvs repository, and server module resides on another cvs repository. You can configure build for this project by creating two normal cvs projects, one for each repository, and incorporating views under them into a composite view.
2. views tab
This page shows all views currently configured under this project, you can create new view or delete existing view from here.

### Chapter 5 - Schedule level pages

The schedule level shows detail information about a particular schedule. There are two tabs in this level: "basic" and "scheduled builds".
1. basic tab
From this page, you can edit some basic information for current schedule, such as name, description, and trigger type, etc.
2. scheduled builds tab
This page lists all views attaching to this schedule. To attach or detach views for this schedule, you should change to the view level pages, as next chapter introduces.

### Chapter 6 - View level pages

The view level shows detail information about a particular view. There are three tabs in this level: "basic", "modules", and "scheduled builds". Please be note that this view is not the same notion as views in some version control systems, such as starteam and clearcase.
1. basic tab
From this page, you can edit some basic information for current view, such as name, description, build file, etc.
1) Common properties for all vcs are listed below:
i) next build version
This property is required. It is the version the next build for this view will be assigned. Generally it should be quoted with quotation marks, and should starts with a letter, should not contain certain characters like "$,:;@". After you set a initial value such as "v1.0" when creating this view, it will keeps increase for every build. So after two builds, when you come to this page, its value will be "v1.2", Anytime you can change this value, for example, to "foobar-1.1.0", then luntbuild will increase the version based on the new version to "foobar-1.1.1", "foobar-1.1.2", ... The increment rules is described by examples as below:
"luntbuild-1.0" will be increased to "luntbuild-1.1"
"luntbuild-1.9" will be increased to "luntbuild-1.10"
"luntbuild-1.5(1000)" will be increased to "luntbuild-1.5(1001)"
Actually the version string is an ognl expression. Luntbuild will evaluate this expression to get the actual version string for a specific build. You can use internally supported variables to make the version expression more flexible. For example, the version expression can be: "luntbuild-"+year+"-"+month+"-"+dayOfMonth+"."+dayOfMonth.iteration. In this way, the actual version string for a build will include the build date and iterations for that date. As you can see, the expression includes characters which are not quoted within the quotation, such as year, month, etc. These are called ognl properties. Here are a list of pre-defined properties: year, shortYear, month, numericMonth, weekOfYear, dayOfWeek, numericDayOfWeek, dayOfMonth, dayOfYear, hour, minute. Every property supports the iteration child property, for example dayOfMonth.iteration. The iteration means how many iterations(or build times) has been executed for specific value of the property. When value of a property changes, the iteration will be reset to 1, and will start increasing once for a build, until its parent property changes to another value.
NOTE: After get the actual version string through ognl expression evaluation, luntbuild will substitute all "." character in the version string to "_", and all blank character to "-", and thus forms the label which will be applied to source codes in the version control system for particular build. For example, if a build has a version "v1.0 build256", source code for this build will be labeled as "v1_0-build256".
NOTE: Because luntbuild will label the source code based on the version number. If there is multiple projects, or multiple views configured in the system, you should make sure there is no patentially duplicated versions for build in the system. For example, if you configure view1 with next build version as "v1.0", and configure view2 with next build version as "v1.5". If both of these view contains same module in the same version control system, after five builds or more, version number of view1 will get duplicated with version number of early builds of view2. So the best practice is to name the version number for each view with project/view prefix, such as "luntbuid-dev-0.9.2".
ii) build necessary condition
This property is optional. If left empty, the "modified" string will be assumed. This property is used by luntbuild to determine if current build is necessary when build strategy of a build schedule is set to "build when necessary". The build necessary condition is an ognl expression. When this expression evaluates to true, the build is considered necessary. Here are some samples to demonstrate format of this ognl expression:
a) modified, this expression will be true if repository content of current view changes
b) view["development"].modified, this expression will be true if repository content of "development" view of current project changes.
c) project["testcvs"].view["development"].modified, this expression will be true if repository content of "development" view of "testcvs" project changes.
d) ant("/path/to/command.xml", "targetA") == 0, this expression will be true if execution of targetA of ant script file /path/to/command.xml success. NOTE: Special characters such as '\', '"', should be escaped with '\', just like java strings. Also if the ant file path will be assumed to relative to current view's working directory if it is not an absolute path. If target equals to "" or null, the default target will be assumed.
e) execute("/path/to/command.sh") == 0, this expression will be true if result code of execution of specified command is 0. NOTE: Special characters such as '\', '"', should be escaped with '\', just like java strings.
f) the above expressions can be prefixed with '!' to inverse the value, for example "!modified " will be true when there is no modifications in the repository of current view.
f) The above expressions can be joined with "and", "or". For example, the expression:
modified or execute("/path/to/command.sh")==0 will be true if repository content of current view changes, or execution of specified command returns 0.
Please access http://www.ognl.org to get more knowledge over general grammer of ognl expression.
iii) build success condition
This property is optional. If left empty, the "result==0" string will be assumed. This property is used by luntbuild to determine whether current build is success or not. The build success condition is an ognl expression. When this expression evaluates to true, the build is considered to be successful. Here are some samples to demonstrate format of this ognl expression:
a) result==0, here "result" represents return code of ant execution of the build file.
b) logContainsLine("^ERROR.*"), the expression will be true if the resulted build log contains a line which matches the regular expression pattern "^ERROR.*". Please access http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html for detailed format of this regular expression.
c) The above expressions can be prefixed with a '!' character to inverse the value. For example, !logContainsLine("^ERROR.*") will be true if the build log does not contains line which matches the specified pattern.
d) The above expressions can be joined with "and", "or". For example, the expression:
result==0 and !logContainsLine("^ERROR.*") will be true if ant execution of build log returns 0, and the resulted build log does not contains any line that starts with "ERROR".
Please access http://www.ognl.org to get more knowledge over general grammer of ognl expression.
iv) ant build script path
This property is required. This is the ant build script which will be called by ant when build current view. It will be assumed to be relative to the view working directory if this path is not an absolute path. Details about how to write this build script will be explained later.
v) ant build target
Specify the target to build. If not specified, the default target in the above build file will be build.
vi) ant post-build script path
This property is required when you want luntbuild to execute a post-build ant script after build. It will be assumed to be relative to the view working directory if this path is not an absolute path. Luntbuild will pre-define some properties when execute this post-build file. These pre-defined properties are the same as those when execute the build file which is described in chapter8.
vii) ant post-build target
Specify the target to for post-build ant script. If not specified, the default target in the above post-build file will be assumed.
viii) ant command
This property is same as described in Chapter3/Section5 except it is view specific and can override the global setting.
viiii) environment file path
This property is same as described in Chapter3/Section5 except it is view specific and can override the global setting.
2) Properties for base clearcase adaptor
i) Explicit path for view storage
This property is optional. If sepcified, it will be used as the -vws to create related clearcase snapshot view, instead of using -stgloc option indicated by the project level property "clearcase view stgloc name"
ii) Config spec
You should specify the config spec for current view. This will be used by luntbuild to create related clearcase snapshot view.
iii) Modification detection config
This property is used to detect if there are any changes in the repository, and thus determine whether it is necessary to perform next build. It will only take effect if there are some LATEST versions from some branch be configured to fetch in the above config spec. This property is comprised of multiple entries with each entry be the format of "<path>[:<branch>]". <path> stands for a path inside a vob which should be visible using the above config spec, and it can not be of value "/" or "\". Luntbuild will lookup any changes at any branch inside this path recursively, or will lookup changes at specified branch if <branch> is specified. Multiple entries are seperated by ";" or line terminator. For example, you can configure this property as the following:
\myvob1:main
myvob2:branch1
Using this property, luntbuild will detect if there are any changes at main branch of path <view working directory>/myvob1, and at branch1 of path <view working directory>/myvob2.
3) Properties for clearcase UCM adaptor
i) Explicit path for view storage
This is the same as base clearcase adaptor
ii) UCM stream name
You should specify a UCM stream here, see below property to get understanding of the necessary.
iii) What to build
Specify baselines you want to build inside the stream. Multiple baselines are seperated by space. The following values are reserved for particular meaning£º
"latest": means build with all latest codes from every component
"latest baselines": means build with all latest baselines from every component
"recommended baselines": means build with all recommended baselines
"foundation baselines": means build with all foundation baselines
iv) Modification detection config
This property will only take effect when whatToBuild property equals "latest". It is used by luntbuild to lookup if there are any changes in the repository since last build. This property is comprised of multiple entries with each entry be the format of "<path>[:<branch>]". <path> stands for a path inside a vob which should be visible using the above config spec, and it can not be of value "/" or "\". Luntbuild will lookup any changes at any branch inside this path recursively, or will lookup changes at specified branch if <branch> is specified. Multiple entries are seperated by ";" or line terminator.
4) Properies for <composite vcs> adaptor
The only property for a <composite vcs> adaptor is the "included basic views". Luntbuild will setup a composite vcs for current view by incorporating all vcs settings of included basic views. In this way, all repository contents of these basic views will be checked out to current view's working directory to perform build. Also refer to composite vcs section for detailed explanation.
2. modules tab
This page defines modules configured for current view. It is not applicable to base clearcase and clearcase UCM adaptor. For other vcs, you can specify multiple modules to form the build contents. The retrieve process will start from first module, to the last module. And later modules will override previous modules if there is some potential overlapped directories or files. For example, if you define module1 with destinatio path be "/foo/bar", and later you define another module with destination path be "/foo", contents of module2 will wholy override contents of module1. But if module1 is defined with destination path be "/foo", and module2 is defined with destination path be "/foo/bar", module1 will only have contents under "/foo/bar" will be overrided by module2. Detail of module definition are described below:
1) For cvs
"source path" represents a module path in the cvs repository, for example "/testcvs", "/testcvs/web", or "testcvs", but you can not define a "source path" like "/" or "\". "branch" stands for a cvs branch and "label" stands for a cvs tag. Only one of these properties will take effect for a particular module. If both of them are not empty, label will take preference over branch. If both of them are empty, luntbuild will get latest codes from main branch for related module.
2) For visual sourcesafe
"source path" represents a project path relative to the root of sourcesafe, for example "testvss", "/testvss", or "/testvss/web", etc. "/" or "\" can be used to retrieve whole contents in the repository. "label" stands for a vss label. Vss implements branches by creating new shared sourcesafe projects. So you may need to configure different modules here in order to get codes from different branches. If label is left empty, luntbuild will get latest codes for that module from vss. If "destination path" is defined., contents from sourcesafe will be retrieved to "destination path" relative to view working directory, otherwise, contents will be put to "source path" relative to view working directory.
3) For subversion
"source path" represents a path into the svn repository, for example "testsvn", "testsvn/web", or "/testsvn". "/" or "\" are not allowed. When "branch" or "label" properties are defined, this path will be mapped to another path into the svn repository. In order to demonstrate this path mapping, We suppose at project level, we define following properties:
repository url base: svn://localhost
directory for branches: branches
directory for tags: tags
And we define a module at the view level with with "source path" be "testsvn/web", "branch" be "simplified-chinese", "label" be "testsvn-dev-1.0", and "destination path" be empty. Firstly, the path "testsvn/web" will be mapped to path "branches/simplified-chinese/testsvn/web" after we apply the branch information. And the mapped path "branches/simplified-chinese/testsvn/web" will be furthur mapped to path "tags/testsvn-dev-1_0/branches/simplified-chinese/testsvn/web" after we apply the label information. So finally luntbuild will execute the following command:
"svn checkout svn://localhost/tags/testsvn-dev-1_0/branches/simplified-chinese/testsvn/web <view working directory>/testsvn/web ... ", where <view working directory> will be subsituted as the actual view working directory. Based on this calculation, the following module definitions will be equivalent:
"source path : testsvn/web, branch: simplified-chinese, label:<empty>, destination path:<empty>" and "source path: branches/simplified-chinese/testsvn/web, branch:<empty>, label:<empty>, destination path:<empty> "
"source path: testsvn/web, branch:<empty>, label:testsvn-dev-1_0, destination path:<empty> " and "source path : tags/testsvn-dev-1_0/testsvn/web, branch:<empty>, label:<empty>, destination path:<empty> "
...
As you may guessed, luntbuild will perform its labelling action to particular build based on above mechanism. For example, in order to set a label "testsvn-dev-1_0" on source path "testsvn/web" with branch "simplified-chinese", luntbuild will perform this command:
"svn copy svn://localhost/branches/simplified-chinese/testsvn/web svn://localhost/tags/testsvn-dev-1_0/branches/simplified-chinese/testsvn/web"
At last, if "destination path" is defined., contents from svn repository will be retrieved to "destination path" relative to view working directory, otherwise, contents will be put to "source path"(with no regard to "branch" or "label" here) relative to view working directory.
4) For starteam
"starteam view " stands for a starteam view, and label stands for a label for this starteam view. If "starteam view " is left empty, the root starteam view will be used. "source path" is a path relative to the root of the choosed starteam view. If "destination path" is defined., contents from starteam repository will be retrieved to "destination path" relative to view working directory, otherwise, contents will be put to "source path" relative to view working directory. For example, you can add a project "teststarteam" at starteam server, and create a view named "simp-china" rooted at root directory of that project. then you can add a luntbuild view and configure a module with source path be "/" , starteam view be "simp-china", label be empty, destination path be empty, etc.
5) For perforce
The module definition for perforce is much like define a view mapping for a client in perforce, except luntbuild supports another property "label" when define this view mapping. "depot path " represent a repository side path, such as "//depot/testperforce/...", "client path" will represent a client side path, such as "//myclient/testperforce/...", and "label" can be a perforce label, if you want to retrieve a static snapshot for that "source path", or it can be left empty to retrieve the head version of "source path". The client defined in "client path" is not necessary to be existed. Luntbuild will create this client if it does not exist, or just edit it if it has existed. The user specified for perforce port at the project level should have enough access rights to create or edit perforce client. For different view under the same project, you should specify different client name in the "client path".
Let's explain usage of modules more detaily. Take cvs for example, suppose there is a module testcvs in the repository with two sub directories: client and server. Suppose client has two branch, ie. the main branch, and the customer1 branch. We can configure a view "customer1" with two modules: source path "testcvs/client" with branch "customer1" and empty label, and source path "testcvs/server" with both branch and label empty. By this way, we can easily setup daily build for product delivered to customer1.

3. scheduled builds tab
The scheduled builds page is something like this:
This page shows information about builds scheduled for the "development" view. For each schedule this view attaches to, there will be an area in the page such as "nightly". Under this section, you can view information about build type, build strategy, label strategy, mail strategy, latest build, etc. When the latest build is not success, the latest success build will also be shown. Also the current running build will be shown if there is any build running.
1) Execution status
The schedule execution status is different from build status. It means whether or not the schedule has been successfully triggered. Trigger of the schedule may or may not generate a new build, depends on current build strategy and repository changes. The schedule execution status maybe "failed" while the build succeed, for example, due to an error in sending notification mail. Also the schedule execution status can be "success" although the build failed, because the schedule has been successfully triggered, and the fail of the build is not his fault, :). Detailed information about execution of a schedule can be found in the system log, which can be accessed through the "system log" link at top of every page.
2) There are two build type: clean build and increment build. To do a clean build, luntbuild will first clean up view working directory, and then do a full checkout for configured modules. To do a increment build, luntbuild will only do a update for source codes checkouted by former builds, all intemediate build files are not cleaned before the new build. So an increment build is surely fast, but it may also have a bigger chance to fail. For example, if someone have delete a file from version control system, and this may not get reflected for a increment build.
3) There are four build strategies: "build when necessary", "build always if failed", and "build always".
"build when necessary" means only performs build when there is any changes detected since last build in this schedule. Changes are considered exist since last build if the following condition meet:
i) Current build is the first build inside current schedule
ii) The vcs setting has changed since last build.
iii) In case the vcs adaptor is clearcase UCM adaptor and "what to build" property is set to a value other than "latest", changes are considered exist if related baselines are changed. For example, if "what to build" is set to "recommended baselines" and the clearcase admin has recommended another different set of baselines since last build, changes are considered to be exist, and thus will cause next build to be performed.
iv) Head revision of related files(or directories) are changed in the repository if current vcs setting indicated to retrieve any files at head revision.
build always if failed: means build will always be performed if last build is failed, however, if last build is success, next build will only be performed when there is any changes detected since last build in this schedule.
build always: means always perform the build at specified schedule trigger time regardless of status of last build and changes in the repository.
do not build: means do not perform the build at any circumstances. This strategy can be used to stop the schedule.
The build strategy is only used when trigger type of the schedule is not "manually".
4) There are three label strategy, respectively: "label successful builds", "always label", "do not label".
label successful builds: label the repository only for successful builds.
do not label: never label the repository after build.
label always: always label the repository after build.
NOTE: if a build is not get labeled when it is initially built, it will not be rebuildable later
5) There are three notify strategy, respectively: "notify when failed", "do not notify", "always notify"
notify when failed: send the notification only when build failed.
do not notify: do not send notification after build.
notify always: always send notification after build.
You can attach current view to new schedules by click the icon at right top area of this tab page. You can detach from a schedule by following the icon of this schedule. You can edit the above properties by following the icon for each schedule. And you can manually trigger a build inside current build schedule by following its icon.
You can attach a particular view to multiple schedules, but only one build will be performed at a given time(including manual build and rebuild) because one view has only one view working directory. For example, if you attach view1 to schedule1 which runs at 1:00AM every day, and you also attach this view to schedule2 which runs at 2:00AM every day. Suppose build for this view takes 2 hours to finish. At 1:00AM every day, luntbuild will start a build. But what happens at 2:00AM when schedule2 should be triggered? The answer is the build for schedule2 will postponed to 3:00AM until the previous build finishes. But if you create another view "view2" under the same project with the same modules with view1, and attach it to schedule2, the build for view2 will be started normally at 2:00AM even if build for view1 has not finished. This is because view1 and view2 has different view working directory and they will not get disturbed.
History builds under each schedule can be accessed by clicking link "history builds" at top of the section. The resulting page is as below:
You can access detail information about a particular build by following the version hyperlink for that build. This will leads you to a page like:
In the "Build artifacts" area of this page, you can download artifacts for this particular build. You can also create new directory as well as upload new artifacts. This can be useful for example if you want to supply patches for specific build. And also you can access the build log for this build. This log can help you diagnostic the problem in case a build fails. The revision log records file or directory changes in the repository between previous build and this build. If you selects to "label build" when generating this build, you will have a "rebuild" hyperlink at top area of this page. Following this link, you will be able to rebuild this build laterly in case the build artifacts losts, etc. The rebuild process will use exactly the vcs setting when that build is initially be built. The exact rebuild vcs setting will be written into the build log when you perform a rebuild. You can return to page showing build scheduling information by clicking on the "scheduled builds" tab.

### Chapter 7 - Writing your ant build file

As introduced in chapter6/section1, you need to provide a build file which will be feed to ant to build your projects. This build file is a standard ant build file. Before run your build file, luntbuild will pre-define the following properties:
1. buildId
This property records the unique identifier for this build in the system. This information can be useful when doing disaster recovering.
2. buildVersion
This property records current version of this build.
3. buildDate
This property records the build time for this build.
4. publishDir
This property specifies the publishing directory for current build. You should generate all your final build artifacts to directory defined by property "publishDir", or its sub directories. This is needed because luntbuild will only present contents under this directory or its sub directories on the web for this build. You can accompilsh this by, for example:
<zip basedir="stage" destfile="${publishDir}/${buildVersion}.zip"/>
These properties are not only useful when writing the ant build file, but also useful when run your application. For example, you can show the build version number on your application about dialog. In order to achieve this, you should write these properties into a file which will be packaged together with your application distribution. You can achieve this by inserting following lines inside some packagint targets of your ant build file:

<propertyfile file="stage/buildInfo.properties">
<entry key="buildVersion" value="${buildVersion}"/>
<entry key="buildId" value="${buildId}"/>
<entry key="buildDate" value="${buildDate}"/>
</propertyfile>

Although luntbuild pre-defines the above properties before run ant, you are encouraged to give those properties default values in the beginning of your build file, such as:

<property name="buildVersion" value="luntbuild-1.0"/>
<property name="buildId" value=""/>
<property name="publishDir" value="distribute"/>
<property name="buildDate" value=""/>

Please be note that, you do not need to redirect any generated outputs or errors to your log file. Just leave them output to stdout or stderr, luntbuild will cpature them and write into the prepared log file and publish at the website.
Luntbuild itself is built through luntbuild. By looking at configuration for the pre-defined project "luntbuild" in the binary distribution and the build.xml file in the source distribution, I am sure you can set up your projects easily.

### Chapter8 - Writing ant build file to wrapper existing makefile or build script

If you already have a makefile or build script, or you are not familiar with ant. An simple ant build script can be written to wrapper again your makefile or build script. Luntbuild shipped with an wrapper sample in the wrapper_sample sub directory to demonstrate this. In this directory, the build.xml file is the sample ant build file which wrappers again the batch file, myscript.bat. Contents of build.xml is listed below with comments describing usage:

<project name="foobar" default="build" basedir=".">
<!-- Set default values for build information properties, these properties will be
overrided by actual value when luntbuild calls this build script. However, these
default value are useful if you want to test your build scripts without run in
luntbuild. In order to test without luntbuild, you need to open an command line window, and
input <path to luntbuild installation directory>/ant/bin/ant -buildfile <path to this build script file>
-->
<property name="buildVersion" value="foobar-1.0 build233"/>
<property name="buildId" value="1"/>
<property name="publishDir" value="d:\publish"/>
<property name="buildDate" value="2004/8/5 11:12"/>
<target name="build">
<!-- Calls the external command using exec task, for detail format of
this task, please refer to http://ant.apache.org/manual/CoreTasks/exec.html
NOTE: you do not need to re-direct outputs or errors of the external command to
some log file, luntbuild will capture them and redirects to the prepared log file
and publish at the website.
-->
<exec command="cmd /c myscript.bat">
<!-- setup environments to transfer build information. External command
should pick up these environment variables in order to use these information.
-->
<env key="buildVersion" value="${buildVersion}"/>
<env key="buildId" value="${buildId}"/>
<env key="publishDir" value="${publishDir}"/>
<env key="buildDate" value="${buildDate}"/>
</exec>
</target>
</project>

Content of myscript.bat is listed as below:

REM This is a sample build script which get called from a wrapper ant build script file
REM here we only print out the build information environment variables. In a real
REM world, you may do these things to utilize these environment variables:
REM 1) suffix your builded output file with value of environment variable "buildVersion"
REM 2) publish your build output into the directory indicated by environment variable "publishDir"
REM 3) write these environment variables into an external file and package that file with your product.
REM By this way, your product can show some build information such as version number at runtime.
echo off
echo Current build version is %buildVersion%
echo Current build id is %buildId%
echo Current build date is %buildDate%
echo Build results should be put into %publishDir%

### Chapter 9 - Use luntbuild remoting API

Luntbuild has provided a suite of remoting API with the following abilities:
1. Trigger build in any build schedule.
2. Config properties of projects, views, as well as global properties
3. Search builds and get build information such as its publishing url, etc.
By utilizing the hessian web service protocol, these APIs are very to use. Basically two jars are needed to be included in the classpath: hessian-3.0.8.jar and luntbuild-remoting.jar which resides in the "remoting" directory. There are also some samples demonstrate usage of these APIs.
The provided TriggerBuild sample can be used to implement a real-time continuous integration, that is, whenever a checkin is made into the repository, luntbuild can be triggered rightaway to build. We will take an example of cvs repository to show how to do this:
1. Create a manual triggered schedule and attach it to the view you want to implement real-time continuous integration. To get the build fast, you can configure it to build incremently.
2. Checkout the CVSROOT directory of your cvs respository, edit the "loginfo" file, and append a line like this:
testcvs cmd /c d:\lunt\cvs\lunt\luntbuild\remoting\samples\trigger_build.bat

Here, testcvs should be replaced with the directory path of your cvs repository. All checkins under this path will trigger the trigger_build.bat command. The file trigger_build.bat resides in the "remoting/samples" directory. Of course, you can copy related files(the remoting API jar files, the TriggerBuild.class file, and the trigger_build.bat file) to any other machine as long as JDK1.4 or upper are installed. The path to trigger_build.bat need to be changed to fit your environment. And content of trigger_build.bat should be changed to reflect proper classpaths, your luntbuild server url, your desired project, view and build schedule. In unix platform, you can create the trigger_build.sh script easily according to contents of trigger_build.bat.
3. Checkin the "loginfo" file. All things now get done. For later checkins under your configured path, it will trigger the trigger_build command, which will result in a build of your changed codes.
Any other version control system that can trigger an external command upon checkin can use this method to implement real-time continuous integration.

### Chapter 10 - Diagnostic build problem

If there is some problem during build of your project, the build log for the failed build is very useful to diagnositic those problems. By default, luntbuild will only write log information with priority equal or greater than MSG_INFO. You can use "-v" or "-verbose" ant option for the "Command to run ant" property as described above to force luntbuild write more detail log information, which may helps you to find problem more accurately. For example, you can configure the property "Command to run ant" as:
/j2sdk1.4.2_04/bin/java -classpath /apache-ant-1.6.1/lib/ant-launcher.jar -Dant.home=/apache-ant-1.6.1 org.apache.tools.ant.launch.Launcher -verbose
Logs about the scheduler itself are written to <luntbuild installation directory>/logs directory. These logs include information about modification detection, and other informations not relate to any specific build. You may need to look at these logs to diagnostic problems such as scheduled or manual build not performed, etc. The latest log file can be accessed through "system log" link at top of every page. However, for older log files, you will need to goto the logs directory.