Test-AutoBuild

The idea of Test-AutoBuild is to automate the building of a project's complete software stack on a pristine system from the high level applications, through the libraries and right down to the smallest part of the toolchain.

With any project of reasonable complexity it is impossible for developers to test their work against every scenario, platfom and related software, so bugs will inevitably creep in to systems. At worst these bugs won't be identified until the code in question is deployed in the production environment or during final release builds. Every bug introduced in the source repository has the potential to block

Test-AutoBuild is a currently maintained by Daniel Berrange and Dennis Gregorovic. In the past, Richard Jones has also been a major contributor of code, also having written the original rollingbuild program from which Test-AutoBuild is derived. There is also a small, but growing, community of developers who provide feedback, suggestions and enhancements. Anyone interested in getting involved in the development should join the developer's mailing list hosted on the project's Gna! site.

For historical reasons, the core Test-AutoBuild software is all covered under the GNU GPL. Additional extension packages (such as the DBus integration modules) are also usually covered under the GNU GPL, since they are typically derived works, although verify by reading the LICENSE file that comes with any software downloaded. The GNOME panel applet for monitoring the module build status is under the GNU GPL. Finally the content on this website is covered under the creative commons XXX license.

Since Test-AutoBuild is written in Perl, all stable releases will be uploaded to CPAN under the directory

The performs nightly builds of both the stable and development branches of CVS on a Debian Woody system. If anyone has spare CPU cycles on other Linux / UNIX operating systems and wishes to provide either a continuous or nightly build, please send a message to the .

Test-AutoBuild currently requires the following Perl modules to be present

File::Copy

A convenience module for copying / moving files. Used by the build cache, package copier and log file copier to avoid a dependancy on the shell 'cp' command.

File::Find

A module for traversing a directory tree locating files satisfying a particular criteria. Used throughout to avoid a dependancy on the UNIX 'find' command.

Find::Path

A module for creating / removing directory trees. Used throughout to simply handling of directory trees.

Digest::MD5

A module for generating MD5 checksums of files. Used by the HTML status page generator to provide checksums for all packages generated by a module build.

Sys::Hostname

A module for identifying the hostname. Used by the HTML status page generator to determine the hostname to use in hyperlinks.

Config::Record

A module for reading configuration files. Used to load the configuaration files at the start of each build cycle.

Template

A module for advanced templating tasks. Used by the HTML status page generator and email alert module for generating HTML files and status messages.

Net::SMTP

A module for communicating with SMTP servers. Used by the email alert generator for sending status messages at the end of each build cycle.

BSD::Resource

A module for adjusting resource limits. Used to lower the priority of the build process to ensure that the system remains relatively responsive during intensive builds.

IO::Scalar

A module for performing I/O on scalars. Used by multiple modules for performing I/O operations in memory.

Test-AutoBuild follows the standard MakeMaker practices for installation, so simply issue the commands:

perl Makefile.PL
make
su -c make install

Once installed it is neccessary to setup a basic directory hierarchy in which builds will be performed. For details of this process, consult the Test::AutoBuild . The final setup step is the edit the default configuration file adding to specify location of the source control repositories and list the modules to check out & build. The sample configuration file is installed in /etc/autobuild/autobuild.conf. The default parameters in this file should work out of the box, if the recommended directory structure is created in /var/builder. So merely edit the 'repositories' and 'modules' parameters, following the examples documented in the file.

First of all check out the adminstration & troubleshooting section of this FAQ for solutions to common issues. If the cause of the bug is clear, then report it to the bug tracker on the Gna! project pages straight away. Otherwise send a mail describing the problem in as much detail as possible to the developer mailing list. Also send a message to the list if you have reported the bug, but require assistance on a possible workaround.

If a previously successful build begins failing for no apparent reason, or if there was a transient failure in the underlying operating system (disk full, network down, etc), some of the builder's state may become corrupt. The first task in such a situation is to delete the entire contents of the build cache. This is typically located in a directory named build-cache within the build home

$ su - builder
# cd /var/builder
# rm -rf build-cache/*

Sometimes the actual source code checkout for a module becomes corrupt (typically either due to broken build scripts / makefiles which change source code during the build process, or transient operating system failures) Thus if cleaning out the build-cache did not solve the failure, then the next step is to delete the contents of the build root (in 1.0.x releases called build-home, renamed to build-root in 1.1.x releases).

$ su - builder
# cd /var/builder
# rm -rf build-home/*

In keeping with the modular design and philosophy of UNIX, the builder script is only intended to run through a single build cycle. Thus it does not contain a built-in build schedular. Instead it is expected that builds be invoked using the standard schedulars present in the host operating system. For UNIX systems this job is typically performed by the Cron daemon. The builder has simple locking capabilities built-in, such that if a build instance is currently active it will silently exit. Thus to implement a continuous build system configure Cron to launch the builder every 5 minutes, by adding a file containing the following to /etc/cron.d

USER=builder
PATH=/bin:/usr/bin:/usr/local/bin
*/5 * * * * builder /usr/bin/auto-build.pl --config /etc/auto-build.d/auto-build.conf

Or, alternatively, add the following to the crontab for the builder user

*/5 * * * * /usr/bin/auto-build.pl --config /etc/auto-build.d/auto-build.conf

The goal of automated builds is to identify software bugs as soon as possible after they are introduced. As the delay between a bug being introduced & its subsequent identification / resolution increases, an ever larger proportion of the development team will be impacted. Even a small bug can quickly lead to significant productivity loose across the entire team. The goal must be to shorten the gap between introducing the bug & identifying it to the smallest interval possible. Thus the ideal scenario is for the automated builds to run continuously 24/7 on a dedicated build machine. If there are not sufficient free CPU resources then a nightly build is the next best option.

If the software is intended to be built and used across many platforms, then it is clearly beneficial to have autobuild instances covering as many of the different platforms as economically possible. This will help ensure that platform specific bugs are identified quickly. This is particularly important if one of the target platforms is Win32 and the rest are *NIX based.

The control file tutorial provides examples illustrating integration with C, C++, Perl and Java programs.

For those interested in getting involved in development of Test-AutoBuild, a good first step is to join the developers mailing list hosted on the project's Gna! site. If you have ideas for new feature enhancements send them to the list for discussion. Alternatively take a look at the task tracker to see if there are any outstanding issues looking for an owner. There is also always a need people who are interested in writing documentation and material for the website.

Feature requests for future development of Test-AutoBuild are managed through the project's Gna! task tracker. For simple items such as a request for support of an additional source control repository tickets can be opened directly, for more complex issues it is helpful to post to the technical mailing lists for a discussion on the matter in question.

Creating a new output module for Test-AutoBuild is simply a case subclassing the virtual Test::AutoBuild::Output base module and implementing the process method. This method is passed four arguments. An array ref for the list of modules, an array ref for the list of groups, an array ref for the list of code repositories and an array ref for the list of package types.

The current development tree is introducing the concept of stages and transaction/workflow engine for co-ordinating them. Adding new stages into the engine will involve providing a new subclass of the Test::AutoBuild::Stage module and adding it to the configuration file.

The virtual base class Test::AutoBuild::Repository defines the API for source control repository integration. For most repository types it will be sufficient to implement the export method. This takes two arguments, the name of the module to export and the module object itself. The path on the module object can be called to retrieve the list of paths to export. The code should be exported into a directory matching the name of the module. The return status of the method should be zero if the module was unchanged since the last export, or non-zero if changes were downloaded.