LuntBuild - Build Automation and Management

User guide

Version 1.0.2

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 - 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!

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. NOTE: The view working directory can be overrided at each view setting.

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.

6) "Server principal's email"

Specify the email address who reponsible for this build server. The email address used by luntbuild to sent build information is in this priority: view principal, project principal, and server principal. Lower priority principal is used only when higher priority principal leaves empty. If all of them are empty, the email will not be send.

7) "SMTP host"

You can optionally specify the SMTP mail host used by luntbuild to send email. If this property is not specified, luntbuild will use localhost as the default value

8) "SMTP user"

This property is optional. If the SMTP host needs authentication, you should provide the user name here.

9) "SMTP password"

This property is optional. If the SMTP host needs authentication, you should provide the password here.

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. Currently only password server protocol is supported. 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:

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) view principal's email

Specify email address of the person who responsible for this view. If it is left empty, necessary email about this view will be sent to the project principal.

ii) view working directory

This property is optional. If specified, it will override the default working directory for current view.

iii) ant build file path

This property is required. This is the ant build script which will be called by ant when build current view. Path of the ant build file is relative to the view working directory. Suppose you input: testcvs/build/build.xml, then file <view_working_directory>/testcvs/build/build.xml should exists after luntbuild have checkouted all modules of this view. Details about how to write this build script will be explained later.

iv) ant build target

Specify the target to build. If not specified, the default target in the above build file will be build.

v) next build version

This property is required. It is the version the next build for this view will be assigned. It should starts with a letter, and 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)
luntbuild-1.0 alpha will be increased to luntbuild-1.1 alpha

NOTE: 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.

vi) ant command

This property is same as described in Chapter3/Section5 except it is view specific and can override the global setting.

vii) 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.


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 modified", "build always if failed", and "build always".

"build when modified" 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 mail strategy, respectively: "mail when failed", "do not mail", "always mail"

mail when failed: send the notification mail only when build failed.

do not mail: do not send notification mail after build.

mail always: always send notification mail 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 - 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.