GOM : Project

A project is the atomic unit of integration. It can describe an installable package or a buildable product. The nested elements of a project definition fall into three different "groups", each optional:

• Build instructions: <ant>, <nant>, <mvn>, <maven>, <configure>, <make> and <script>.
  Describes how to produce the outputs from the inputs.
• Inputs: <depend>, <option>, and <work>. Describes where to find the inputs (primarily jar files, but can be directories and files).
• Outputs: <home> and <jar>. Describes where to locate the output files.

depend

Specifies the name of a required prerequisite project. If a definition for that project is not found in the workspace, the generation will fail.

For a build "all", the invocation of ant or the script is bypassed if any of the outputs of the specified project can not be found.

For both script and ant based builds, any jars defined by the specified project as outputs are added to the CLASSPATH prior to invoking the build operation, unless you nest a <noclasspath> element into the <depend> element.

option

Specifies the name of an optional prerequisite project. If a definition for that project is not found in the workspace, the dependency is ignored.

For both script and ant based builds, any jars defined by the specified project as outputs are added to the CLASSPATH prior to invoking the build operation, unless you nest a <noclasspath> element into the <option> element. If the files are not present, this will have little effect.

work

Adds a directory or a file to the class path. This is to allow projects which have compilation dependencies on byproducts of the build (e.g., tests which import the project itself). This is necessary when using the Ant build.sysclasspath="ignore".

If the directory is not present prior to the build, some VMs may drop it from the CLASSPATH. If this happens, use a <mkdir> element to create it before building the project.

If this directory is deleted during the course of the build, the behavior of the JVM may become unpredictable. The same is true if the element points to a jar file and that file is modified during the build.

If neither the parent nor the nested attributes are present, then the srcdir for the module is added to the classpath.

Note that the entries specified by <work> elements are prepended to the class path. If a class can be found both in a <work> entry and a jar refered to by <depend>, the one from the <work> entry will be loaded.

home

The home directory for a project is the directory which contains the files referenceable by another project. In many cases, it is possible for another project element by the same name (see the overview) to extend a project definition for an installable package in such a way that the result actually builds the project.

A home attribute on a project definition will override this value.

A package attribute on a project will provide a default for this value. Such a default would be relative to the workspace pkgdir

If none of these attributes or elements, the default value is the srcdir for the module.

license

The filename of the license, relative to the src directory. This file will accompany any redistributable jars.

jar

The name of an output jar, relative to the home directory.

javadoc

This declares where the outputs of the javadoc tool outputs are placed. This option only has any meaning if the <javadoc> element is present in the workspace definition.

<javadoc> supports a nested <description> element, which can be used to set the title in the javadoc listing. If no <description> element has been specified, the title defaults to the description of the project. <description> itself only supports nested text and an optional dir attribute.

The <javadoc> elements of all projects are used to create two pages, "javadoc.html" (like this) and "nojavadoc.html" (like this) listing the available sets of documentation and the modules without documentation.

There are three different layouts a <javadoc> element may create in the javadoc listing "javadoc.html":

1. This is the only <javadoc> element associated with the module, the result will look like
   
   label - description
   
   
2. There are several <javadoc> elements associated with the module, their labels are different from the name of the module - the result will look like
   
   name of the module - description of the module
   label - description
   label2 - description2
   
3. There are several <javadoc> elements associated with the module, their labels are all the same as the name of the module - the result will look like
   
   name of the module - description of the module
   description
   description2
   

label in this lists will be created from the project attribute and description from the description child element of <javadoc>

If a given project wants to publish more than one javadoc set, multiple <description> elements like in

    <javadoc nested="java/build/docs/javadocs" project="xml-xerces2">
      <description dir="api">XML Standard API</description>
      <description dir="xni">Xerces Native Interface</description>
      <description dir="xerces">Xerces2 Implementation</description>
      <description dir="other">Other Classes</description>
    </javadoc>
		

must be used.

junitreport

This declares where the outputs of the junitreport tool outputs are placed. This option only has any meaning if the <junitreport> element is present in the workspace definition.

<junitreport> supports a nested <description> element, which can be used to set the title in the junitreport listing. If no <description> element has been specified, the title defaults to the description of the project. <description> itself only supports nested text and an optional dir attribute.

The <junitreport> elements of all projects are used to create a single page, "junitreport.html" (like this) listing the available sets of junit reports.

There are three different layouts a <junitreport> element may create in the junitreport listing "junitreport.html":

1. This is the only <junitreport> element associated with the module, the result will look like
   
   label - description
   
   
2. There are several <junitreport> elements associated with the module, their labels are different from the name of the module - the result will look like
   
   name of the module - description of the module
   label - description
   label2 - description2
   
3. There are several <junitreport> elements associated with the module, their labels are all the same as the name of the module - the result will look like
   
   name of the module - description of the module
   description
   description2
   

label in this lists will be created from the project attribute and description from the description child element of <junitreport>

If a given project wants to publish more than one junitreport set, multiple <description> elements like in

    <junitreport nested="java/build/docs/reports" project="xml-xerces2">
      <description dir="api">XML Standard API</description>
      <description dir="xni">Xerces Native Interface</description>
      <description dir="xerces">Xerces2 Implementation</description>
      <description dir="other">Other Classes</description>
    </junitreport>
		

must be used.

nag

If this element is present, an entry for this project will be created in the file naglist. This enables email reports of build failures.

A build failure is detected by matching the output of the build against Perl regular expressions, the default expression is /BUILD FAILED/i. The regular expressions are specified using nested regexp elements - you can associate different email addresses and subjects with each expression.

The regexp element supports the same attributes as the nag element with an additional (required) pattern attribute. This attribute specifies the Perl regular expression to be used when looking for a build failure.

The nag element itself can be used to set default values for nested child elements:

<nag from="from@example.org" to="to@example.org" />

is a short-cut for

<nag>
  <regexp pattern="/BUILD FAILED/i"
          from="from@example.org" 
          to="to@example.org" 
          subject="Build Failure - @name of project element@"/>
</nag>

Multiple regexp elements may be specified. The first pattern that matches will be the one used to send the nag email.

To send email on success or failure, you could use:

<nag>
  <!-- pattern default is /BUILD FAILED/i -->
  <regexp from="from@example.org" 
          to="to@example.org" 
          subject="Build Failure - @name of project element@"/>
  <regexp pattern="/BUILD SUCCCESSFUL/"
          from="from@example.org" 
          to="to@example.org" 
          subject="Gump Build Success - @name of project element@"/>
</nag>

You may want to nag on deprecation if you are particularly sensitive to a given dependency. The nag for that would look like this:

<nag>
  <!-- pattern default is /BUILD FAILED/i -->
  <regexp from="from@example.org" 
          to="to@example.org" 
          subject="Build Failure - @name of project element@"/>
  <regexp pattern="/deprecat/"
          from="from@example.org" 
          to="to@example.org" 
          subject="Gump Build Warning - Deprecated methods used"/>
</nag>
	

redistributable

If present, indicates that outputs of builds from this module are redistributable. Defaults to the redistributable value for the repository.

mkdir

Creates a directory before starting the build. This is sometimes needed in conjunction with <work>.

delete

Deletes a directory before starting the build.