Apache Gump™

More on builders

Apache Gump supports building projects with a wide variety of tools. These tools are described using their own elements, all of them support a common set of attributes and nested elements. The common structure is described in the next section, followed by tool-specific sections later on.

Generic Builder

Specifies the arguments to be passed to all builders

Attribute	Description	Required?
basedir	The base directory in which the build is executed. The generated build script will make this directory the current working directory prior to invoking the real builder.	No. Defaults to project basedir.
debug (Ant/Maven/NAnt/Gradle/MSBuild only)	Set to "true" to turn on debugging.	No
timeout	Timeout after which a build is terminated if it doesn't complete. Given in seconds	No. Defaults to 60 minutes.

property/arg

Java Property overrides to be passed to the Ant/Maven/Gradle command or command line arguments passed to Script/Configure/Make. The Java builders Ant, Maven, MSBuild and Gradle as well as NAnt use <property> while Script, Configure and Make use <arg> as the name of the nested element.

Attribute	Description	Required?
name	Name of the property to set.	Yes
value	Desired value	No
project	The name of the referenced project. Required if the reference attribute is "home", "jar", "jarpath", "output", "outputpath", or "srcdir".	No
reference	One of the following values: home: the home directory for the referenced project output: the simple name (path relative to home) of the output in a referenced project. jar: the simple name (path relative to home) of the jar in a referenced project. This is similar to outputpath with a outputtype attribute of "jar" but also applies to outputs of type "boot" and "testsjar". outputpath: the fully qualified path of the output in a referenced project. jarpath: the fully qualified path of the jar in a referenced project. This is similar to outputpath with a outputtype attribute of "jar" but also applies to outputs of type "boot" and "testsjar". srcdir: the srcdir for the module containing the project.	No
path	a path which is to be interpreted relative to the srcdir for the module containing the project if specified, or this project otherwise. This option is ignored if reference is specified.	No
id	Specifies which output is desired. Required only for projects which define more than one output of the same type.	No
outputtype	Specifies which type of output is desired. Required only if the reference attribute is "output" or "outputpath".	No

depend

This is equivalent to a property reference="jarpath" as well as a dependency element in the enclosing project. This was introduced as that has become a common enough practice that it makes sense to introduce this element.

Depend is only supported by the Java builders Ant, Maven (any version) and Gradle.

Attribute	Description	Required?
property	The name of the property which will receive the full jarpath of the specified jar.	Yes
project	The name of the project depended on.	Yes
id	Specifies which jar is desired. Required only for projects which define more than one jar.	No
runtime	Specifies whether this dependency is needed at runtime. Choices are "true" and "false" with the default being false.	No

jvmarg

Additional command line parameters to pass to the Java Virtual Machine running Ant, Maven (any version) and Gradle. Doesn't have any effect on any of the other builders.

Attribute	Description	Required?
value	The parameter to pass to the command line. This will be passed verbatim without any additional quotes.	Yes

sysproperty

Java system property to be passed to the Java Virtual Machine.

Sysproperty is only supported by the Ant and Gradle builders.

Attribute	Description	Required?
name	Name of the property to set.	Yes
value	Desired value	No
project	The name of the referenced project. Required if the reference attribute is "home", "jar", "jarpath", or "srcdir".	No
reference	One of the following values: home: the home directory for the referenced project jar: the simple name (path relative to home) of the jar in a referenced project. jarpath: the fully qualified path of the jar in a referenced project. srcdir: the srcdir for the module containing the project.	No
path	a path which is to be interpreted relative to the srcdir for the module containing the project if specified, or this project otherwise. This option is ignored if reference is specified.	No
id	Specifies which jar is desired. Required only for projects which define more than one jar.	No

ant

Specifies the arguments to be passed to Apache Ant.

Attribute	Description	Required?
buildfile	The ant build file to execute. Defaults to build.xml.	No Defaults to build.xml.
target	The ant target to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to the default target defined by the build file.

mvn1

Specifies the arguments to be passed to Apache Maven 1.x.

The Maven 1.x component of Gump (<mvn1>) uses a pre-installed version of Maven, it does NOT bootstrap Maven from svn trunk.

Gump generates a build.properties file for Maven, in which it specifies the jar overrides, and also any properties that are passes into the <maven> element.

Gump does not read the Maven project.xml (POM) to attempt to determine dependencies, the Gump descriptor needs to have them. The 'gump' goal in Maven ought generate such a file.

The element name maven can be used as an alias for mvn1.

Attribute	Description	Required?
goal	The Maven goal to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to jar.

mvn2

Specifies the arguments to be passed to Apache Maven 2.x.

The Maven 2.x component of Gump (<mvn2>) uses a pre-installed version of Maven 2.x, it does NOT bootstrap Maven from svn trunk.

First of all, all mvn built projects use the same local repository for artifacts they've downloaded and this local repository is wiped out after each Gump run. This can be overriden on a per build basis, see below.

When Gump starts up, it starts a web application on the build server that acts as a proxy for mvn repository requests. Whenever a project has been built successfully Gump registers the created artifacts with this proxy. When the proxy is asked for a jar artifact and a jar with matching group and artifact id has been registered, the proxy will completely ignore the specified version and serve the Gump built jar file - and calculate SHA1 as well as MD5 checksums for them on the fly as needed. Any other request that is unknown to the proxy will be passed on to the central mvn repository, in particular the proxy will never serve POMs itself.

Technically it is not necessary to declare the dependencies of a mvn built project since artifacts will be retrieved from the proxy even if Gump doesn't know about the dependency. This can only work if the dependency has already been built, though, so it is still better to list all dependencies inside the Gump descriptor in order to maintain correct build order.

Maven 2.x and some of its plugins will also download jars even if the project itself doesn't need them. It is a good practice to watch the log file of the repository proxy and add the jars that have been obtained from the central repository as explicit dependencies to the projects that have asked for them.

Sometimes a project simply cannot depend on another project built by Gump since it would cause a dependency cycle. One such example is BCEL, which is needed by Xalan and thus transitively by a lot of other projects. BCEL is built using Maven 2.x and uses a plugin that depends on JMock and commons-lang, both of which transitively depend on BCEL. The way around this is to allow BCEL to obtain those jars from the central repository (by being built first) but make it use a separate local repository so that subsequent requests for JMock and commons-lang by other projects will use Gump's versions instead of the released ones.

The element name mvn can be used as an alias for mvn2.

Attribute	Description	Required?
goal	The Maven goal to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to package.
profile	The Maven profile to activate.	No. Gump will use the default profile if the attribute has not been set.
separateLocalRepository	Normally all <mvn> builds share the same local repository that will be removed after each complete Gump run. Sometimes a project needs to use a separate local repository from the others, the most common case is that a project needs to be built against a released dependency instead of a Gump built one in order to break a dependency cycle. The value of this attribute can be a boolean or an identifier. If you use a boolean it simply en- or disables a local repository separate from the other directories and Gump will choose a directory name (if the value is true). If several projects are tightly related and should share the same local repository different from the other projects you can use an id instead of a boolean and use the same id for each project.	No. Defaults to false.

mvn2install

Installs a file into the local Maven 2.x+ repository using the mvn2 install plugin.

This element is a shortcut for a common use case of the mvn builder which would otherwise involve several nested property elements. It uses mvn's "install:install-file" goal to install the file given by the file attribute using the groupId of the current project (or workspace) and the given or implied artifactId.

If the artifact to install is a POM, Gump can try to parse the file for the version number. Gump's parser isn't complete and may be unable to extract the proper version - for example, Gump will not support property references - in which case the version must be specified explicitly.

The element name mvninstall can be used as an alias for mvn2install.

Attribute	Description	Required?
version	The version of the artifact to install.	Yes if `packaging` is different from "pom" or the version inside the POM uses property references.
file	The file to install (relative to basedir).	No. Defaults to "pom.xml".
packaging	The type of artifact to install.	No. Defaults to "pom".
artifactId	The id of the artifact to install.	No. Defaults to project's name.
profile	The Maven profile to activate.	No. Gump will use the default profile if the attribute has not been set.
separateLocalRepository	Normally all <mvn> builds share the same local repository that will be removed after each complete Gump run. Sometimes a project needs to use a separate local repository from the others, the most common case is that a project needs to be built against a released dependency instead of a Gump built one in order to break a dependency cycle. The value of this attribute can be a boolean or an identifier. If you use a boolean it simply en- or disables a local repository separate from the other directories and Gump will choose a directory name (if the value is true). If several projects are tightly related and should share the same local repository different from the other projects you can use an id instead of a boolean and use the same id for each project.	No. Defaults to false.

]]>

is completely equivalent to

]]>

mvn3

Specifies the arguments to be passed to Apache Maven 3.x.

The Maven 3.x component of Gump (<mvn3>) uses a pre-installed version of Maven 3.x, it does NOT bootstrap Maven from svn trunk.

The mvn3 builder works the same way as the mvn2 builder and supports all the same attributes and nested elements.

mvn3install

Installs a file into the local Maven 2.x+ repository using the mvn3 install plugin.

This builder is identical to the mvn2install builder but uses Maven 3.x rather than 2.x to invoke the install plugin.

]]>

is completely equivalent to

]]>

gradle

The Gradle builder is a work in progress and may not be working correctly.

The Gradle component of Gump (<gradle>) uses a pre-installed version of Gradle, it does NOT bootstrap Gradle itself.

All gradle builds use the same local repository as the Maven builds and are told to always refresh the dependency cache. This can be overriden on a per build basis, see below. The local repository is wiped out after each Gump run.

All gradle builds are run using a special init script that adds all snapshot repositories known to Gump as well as the local maven repository as repositories and changes the version of all dependencies to integration.latest. This means the build will most likely use the latest SNAPSHOT build published by the dependency - in general this is not the version just built by Gump.

Technically it is not necessary to declare the dependencies of a gradle built project since artifacts will be retrieved even if Gump doesn't know about the dependency. Still it is better to list all dependencies inside the Gump descriptor in order to maintain correct build order.

Attribute	Description	Required?
task	The Gradle task to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to build.
separateLocalRepository	Normally all <mvn> and <gradle> builds share the same local repository that will be removed after each complete Gump run. Sometimes a project needs to use a separate local repository from the others, the most common case is that a project needs to be built against a released dependency instead of a Gump built one in order to break a dependency cycle. The value of this attribute can be a boolean or an identifier. If you use a boolean it simply en- or disables a local repository separate from the other directories and Gump will choose a directory name (if the value is true). If several projects are tightly related and should share the same local repository different from the other projects you can use an id instead of a boolean and use the same id for each project.	No. Defaults to false.

script

Specifies a script to be executed in order to make build a project.

The assumption is that the script can be invoked in a platform independent manner, though the contents of the script may be platform specific. Specifically, if the name of the script is "name" and no file with the name "name" exists in the project's basedir, it will be invoked as follows:

On Windows/batch, "call .\name.bat"
On Unix/bash, "./name.sh"

Attribute	Description	Required?
name	The name of the script to execute.	Yes

Additional command line arguments can be specified using nested <arg> elements. If the name of an arg start with "--" or doesn't start with "-", then a single argument gets created from one <arg> element, using "=" to join name and value. If it starts with a single "-", two arguments get created, one for the name and one for the value. For example:

becomes

./foo --double-dash=1 -single-dash 2 no-dash=3

configure

Is a specialized version of script with the fixed script name of "configure".

make

Specifies the arguments to be passed to make.

Attribute	Description	Required?
makefile	The make file to execute. Defaults to Makefile.	No Defaults to Makefile.
target	The make target to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to ALL.

nant

Specifies the arguments to be passed to NAnt.

Attribute	Description	Required?
buildfile	The NAnt build file to execute. Defaults to NAnt.build.	No Defaults to NAnt.build.
target	The NAnt target to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to the default target defined by the build file.

nuget

Currenty the nuget builder will fetch what has been specified in the packages.config rather than replacing things with the latest version - which would be more in line with Gump's purpose..

The NuGet component of Gump (<nuget>) uses a pre-installed version of nuget.

Attribute	Description	Required?
command	The nuget command to execute.	No. Defaults to restore.
solution	The solution holding the package configuration.	Yes

msbuild

Specifies the arguments to be passed to MSBuild or xbuild. Gump will automatically detect whether MSBuild or xbuild is present and run the appropriate tool - preferring MSBuild.

Attribute	Description	Required?
buildfile	The MSBuild build file/project/solution to execute.	No
target	The MSBuild target to invoke. This can be a comma separated list. Spaces are preserved.	No. Defaults to the default target defined by the build file.