What it is?

commonsbuild is a generic ant build script which is capable to build a single eclipse project but also a complete hierarchy of projects.
Since all information like the project's classpath are allready defined in an eclipse project there's no need to define it again in a seperate file: commonsbuild will read the .classpath file.

So all you have to do is to include commonsbuild's commons.xml ant file.
There's a template file included in the distribution showing this:

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="dist" name="yourProjectName">
    
    <property file="${basedir}/build.properties.${user.name}" />
    <property file="${basedir}/build.properties" />
    
    <property name="common.dir" value="../commonsbuild" />
    <import file="${common.dir}/common.xml" />
</project>

When installing the PMD and ASM plugin these lines above are all you have to do for:

compiling the project classes
creating a project.jar
creating a project-nodeps.jar that includes all the project's libraries classes
creating zip files holding the project's jars
compiling the test cases
executing the test cases
generating PMD reports (see Plugins)
generating findbugs reports (see Plugins)

I use this system to build the software releases on my developer machine but also use the same build scripts on a hudson CI server.

Where to extract/place commonsbuild

There are different possibilities how to work with commonsbuild:

Extract commonsbuild to eclipse's workspace root
Place it where you like ant pass common.dir property to ant (e.g. ant -Dcommon.dir=/path/to/commonsbuild)
Checkin the zip files into a project of your choice and use bootstrap (use the templates/bootstrap.xml we provide) to get commonsbuild extracted to tmpdir.
To use the bootstrap mechanism you have to include this call to your build.xmls (see templates/build.xml):
<ant inheritall="true" inheritrefs="true" antfile="../yourbootstrap/bootstrap.xml"/>
<import file="../yourbootstrap/bootstrap.xml" />

Howto

All you have to do is to copy this template in each project you'd like to get build by commonsbuild and insert the project's name (the module name) in each copy.
If you'd like to use settings on a machine that differs from the standard settings I suggest to define the differences in build.properties.<yourUsername>.
This file is read first so all values defined there are set (and cannot be overriden).

JUnit

If you have a src_test folder these classes will get compiled and executed by ant's JUnit-Task.
To get this work you have to checkin the junit.jar into your SCM system and reference it like any other jar (not via an eclipse container since these are not available on a plain build server).

Plugins

Commonsbuild comes with a module concept, after a successful build all plugins are called.
You can download to plugins from the sourceforge homepage: PMD and findbugs.
If you download the plugins and extract them to commonsbuild's plugins dir they will be executed automatically.

Howto override target

In some cases it is necessary to override a target because you have to do something other at a common target our you'd like to to some pre- or post- actions.
Although commonsbuild defines standard targets to build most projects it offers the possibility for easy integration:
Each target that is thought to be overriden is named xxxHook (e.g. compileHook). So if you'd like to do the compilation on your own you'd define a target named compileHook inside the project's build.xml.
If you'd like to do some pre- or post- actions you'd override xxx-post respectively xxx-pre.
None of the pre-, -hook, post- actions have dependencies so you have not to care about, just override the target: Dependencies are handled inside commonsbuild.

I do override the jarHook and shringHook targets in some projects where I do include external jars inside my project.jar and shrink this file later in the build process to purge all unreferences classes (using an ofuscator/shrinker).

All files can be downloaded from http://sourceforge.net/projects/commonsbuild/