Gump
More on builders
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 only) | Set to "true" to turn on debugging. | No |
property/arg
Java Property overrides to be passed to the Ant/Maven command or command line arguments passed to Script/Configure/Make. The Java builders Ant and Maven 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", 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 |
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 and Maven.
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 or Maven.
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 Java builders Ant and Maven.
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 |
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:
<script name="foo"> <arg name="--double-dash" value="1"/> <arg name="-single-dash" value="2"/> <arg name="no-dash" value="3"/> </script>
becomes
./foo --double-dash=1 -single-dash 2 no-dash=3
ant
Specifies the arguments to be passed to 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. |
maven
Specifies the arguments to be passed to Maven 1.x.
The Maven 1.x component of Gump (<maven>) uses a pre-installed version of Maven, it does NOT bootstrap Maven from svn trunk, yet.
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.
Attribute | Description | Required? |
---|---|---|
goal | The Maven goal to invoke. This can be a comma separated list. Spaces are preserved. | No. Defaults to jar. |
mvn
Specifies the arguments to be passed to Maven 2.x.
The Maven 2.x component of Gump (<mvn>) uses a pre-installed version of Maven 2.x, it does NOT bootstrap Maven from svn trunk, yet.
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.
Attribute | Description | Required? |
---|---|---|
goal | The Maven goal to invoke. This can be a comma separated list. Spaces are preserved. | No. Defaults to package. |
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. | No. Boolean that defaults to false. |
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. |
by Sam Ruby, Adam R. B. Jack