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> 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.

Note that <depend> elements nested within <ant> elements are precisely equivalent to specifying both a property to be passed to Ant, as well as a separate depend element.

Attribute	Description	Required?
name	The name of the project.	Yes
target	Override the ant target to be used.	No

ant

Identifies this project as "buildable", and specifies the target to build and the properties to be passed to ant. The full description of this XML element can be found here Jakarta Ant is the defacto build tool used by a large number of Open Source Java projects.

script

Identifies this project as "buildable", and specifies the script to be executed in order to make this happen. 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", it will be invoked as follows: At the present time, the only use of this is during the bootstrap process for Ant. On Windows/batch, "call .\name.bat" On Unix/bash, "./name.sh" Attribute Description Required? name The name of the script to execute. Yes

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. Attribute Description Required? project The name of the project depended on. Yes inherit Specifies whether dependendencies of this dependency are to be inherited. Default is "none". Other choices are "all" which will copy all dependencies as, "runtime" which will only copy the runtime dependencies, and "hard" which will not only copy all dependencies, but will also convert option elements into depend elements in the process, and "jars" which will actually copy the dependent jars into the list of jars exported by this project. No runtime Specifies whether this dependency is needed at runtime. Choices are "true" and "false" with the default being false. No ids Space separated list of ids for the jars this project depends on. Can be used if only a subset of all jars is needed. If ommitted, all jars of the referenced project will be used. No

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. If the files are not present, this will have little effect. Attribute Description Required? project The name of the project depended on. Yes inherit Specifies whether dependendencies of this dependency are to be inherited. Default is "none". Other choices are "all" which will copy all dependencies as, "runtime" which will only copy the runtime dependencies, and "hard" which will not only copy all dependencies, but will also convert option elements into depend elements in the process. No runtime Specifies whether this dependency is needed at runtime. Choices are "true" and "false" with the default being false. No ids Space separated list of ids for the jars this project depends on. Can be used if only a subset of all jars is needed. If ommitted, all jars of the referenced project will be used. No

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". It generally is OK if the directory is not present prior to the build. However, if this directory is deleted during the course of the build, the behavior of the JVM may become unpredictable. If neither the parent nor the nested attributes are present, then the srcdir for the module is added to the classpath. Attribute Description Required? parent Name of a directory or file, relative to the base directory of the workspace. No nested Name of a directory or file, relative to the srcdir of the module containing this project. No

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. Attribute Description Required? parent Name of a directory or file, relative to the base directory of the workspace. No nested Name of a directory or file, relative to the srcdir of the module containing this project. No

jar

The name of an output jar, relative to the home directory. Attribute Description Required? name The name of the jar Yes id Provides a unique id which can be used to provide selection between multiple jars definitions. No type If the value of this attribute is "boot" then the jar is prepended to the bootclasspath instead of being appended to the classpath. This attribute is ignored unless bootclass="yes" is specified on the workspace. No

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. Attribute Description Required? nested Name of a directory or file, relative to the srcdir of the module containing this project. Note that this ignores any <home> settings. No parent Name of a directory or file, relative to the base directory of the workspace. No project Label to use in the javadoc listing (see below). Default is the name of the project. No module Make the entry for this project in the javadoc listing (see below) appear under the named instead of the enclosing module. No <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": This is the only <javadoc> element associated with the module, the result will look like label - description 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 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.

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. Attribute Description Required? subject value for the Subject header of the mail report. Defaults to "Build Failure - " and the name of the project. Will be prefixed by the prefix defined in the workspace. No from Sender address for the email report. Yes, unless there is a "from" attribute in each nested regexp element. to Recipient of the email report. Will be overridden by a "to" attribute in the workspace. Yes, unless there is a "to" attribute in each nested regexp element. A build failure is detected by matching the output of the build against Perl regular expressions, the default is /BUILD FAILED/. 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/" from="from@example.org" to="to@example.org" subject="Build Failure - @name of project element@"/> </nag>