Delivered-To: mailing list ant-dev@jakarta.apache.org Received: (qmail 3323 invoked by uid 97); 6 Jun 2002 12:53:46 -0000 X-Antivirus: nagoya (v4198 created Apr 24 2002) Date: 6 Jun 2002 12:53:40 -0000 Message-ID: <20020606125340.74650.qmail@icarus.apache.org> From: adammurdoch@apache.org To: jakarta-ant-myrmidon-cvs@apache.org Subject: cvs commit: jakarta-ant-myrmidon/site/src/xdocs buildfile.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N adammurdoch 2002/06/06 05:53:40 Modified: site/src/xdocs buildfile.xml Log: Added more examples, removed the hard-coded list of tasks. Revision Changes Path 1.5 +168 -165 jakarta-ant-myrmidon/site/src/xdocs/buildfile.xml Index: buildfile.xml =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/src/xdocs/buildfile.xml,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- buildfile.xml 2 Jun 2002 14:05:55 -0000 1.4 +++ buildfile.xml 6 Jun 2002 12:53:40 -0000 1.5 @@ -9,75 +9,120 @@

-You define a build process using a project. A project -describes what needs to be done to perform the build. You define a project -by breaking it up into several smaller steps, or targets. -Targets represent the main stages of your build. For example, a project might -have a target that compiles the Java source files, another target that runs unit -tests, and a third target that assembles a distribution. -

+ You define a build process using a project file. A + project file is an XML file, which describes what needs to be done to + perform the build. A project is usually made up of several stages, + or targets. For example, a project might be made up + of a target that compiles the Java source files, another target that runs + unit tests, and a third target that assembles a distribution. +

-A target may depend on other targets. For example, a target that -builds a distribution, cannot do its work until the source files have been -compiled. Myrmidon makes sure that targets are executed in the correct order, -so that a target is executed before the targets that depend on it. -

+ A target may depend on other targets. For example, a target that + builds a distribution, cannot do its work until the source files have been + compiled. Myrmidon makes sure that targets are executed in the correct order, + so that a target is executed before the targets that depend on it. Target + are only executed once. +

-You define a target using basic units of work called tasks. -Tasks can range from the most simple operations, such as copying a file, or -setting a property, up to complex operations like compiling Java source, or -running a test suite. -

+ You define a target using basic units of work called tasks. + Tasks can range from simple operations, such as copying a file, or setting a + property, up to complex operations like compiling Java source, or running a + test suite. +

+ +

+ Let's look at a simple example. The project below contains two targets, + called compile and build-jar. The compile + target executes the javac task, which, as you probably + guessed, compiles up a bunch of Java source files. + The build-jar target depends on the compile target, + which means that it will only ever get executed after the + compile target has been executed. The build-jar + target executes the jar task, which assembles the compiled + class files into a Jar file. +

+ + + + + + + + + + + + + + + +]]>

-A project file is an XML file that defines a single project. The root element -of a project file must be a <project> element. -It can take the following attributes: -

+ A project file is an XML file that defines a single project. The root element + of a project file must be a <project> element. + It can take the following attributes: +

- - - - - - - - - - - - - - - - - - - - - - -

Attribute	Description	Default Value
name	The project name.	The name of the project file, with the extension removed.
basedir	The base directory for the project. The base directory is used - to resolve all relative file names used in the project file. -	The directory containing the project file.
default	The name of the default target.	`main`
version	The project file format version that the project is written for.	None, must be `2.0`

+ + + + + + + + + + + + + + + + + + + + + + +

Attribute	Description	Default Value
name	The project name.	The name of the project file, with the extension removed.
basedir	The base directory for the project. The base directory is used + to resolve all relative file names used in the project file. +	The directory containing the project file.
default	The name of the default target.	`main`
version	The project file format version that the project is written for.	None, must be `2.0`

-A <project> element can contain the following elements, -in the order given below: -

- -

Project references
Initialization tasks
Targets

+ A <project> element can contain the following elements, + in the order given below: +

+ +

Project references
Initialization tasks
Targets

+ +

Below is a simple example, which contains two targets:

+ + + + + ... + + + + ... + + +]]> @@ -104,7 +149,6 @@ project-name->target-name. Here is a simple example:

@@ -120,22 +164,27 @@ -

Initialization tasks are run before any of the project's targets are run, and -are used to initialize the project. Any task can be used as an initialization -task, including <property> and data-type instances. An example:

+ Initialization tasks are executed before any of the + project's targets are executed, and are used to initialize the project. + Any task can be used as an initialization task, including + <property> and data-type instances. The initialization + tasks are executed in the order they appear in the project file. +

-Below is an example:

+ + - - - + Set classpath to ${classpath} + - .. do some stuff .. + ... @@ -143,123 +192,77 @@ - - -

Targets have a similar format to targets in Ant 1.x, though some of the -behaviour is different. A <target> element takes the -following attributes:

- - - - - - - - - - - - - -

Attribute	Description	Default Value
name	The name of the target.	Required
depends	A comma-separated list of targets that this target depends on. - This list can contain targets from referenced projects.	None

- - -

- Listed below are some of the current set of tasks. You can find example - usages of these tasks in the sample project file src/make/sample.ant. + A target is a list of tasks, contained in a <target> + element. When the target is executed, the tasks are executed in the order + they appear in the project file. A target may also have a list of dependencies. + These are targets that must be executed before the target is executed.

`<condition>`

- -

Sets a property if a particular condition is true. See - Conditions for a list of available conditions.

A <target> element takes the following attributes:

`<fail>`

Causes the build to fail.

+ + + + + + + + + + + + + + + + + +

Attribute	Description	Default Value
description	A description of the target.	None
depends	A comma-separated list of targets that this target depends on. + This list can contain targets from referenced projects.	None
name	The name of the target.	Required

`<if>`

Conditionally executes a set of tasks.

An example project, with two targets:

`<load-properties>`

Loads a set of properties from a file.

- -

`<log>`

Writes a log message.

- -

`<property>`

Sets a property.

- -

`<try-catch>`

Runs a set of tasks, with a provided error and clean-up handler.

+ -

`<converter-def>`

+ + + -

`<type-def>`

+ + + -

`<import>`

+ +]]>

- -

The following conditions are available

- -

`<and>`

Evaluates a set of nested conditions, and AND them together. Evaluation is - lazy. An empty <and> condition evaluates to true.

- -

`<available>`

Tests if a particular class or resource is available.

- -

`<file-test>`

Tests a file against a set of file selectors.

`<is-set>`

Tests whether a proeprty is set, and not set to 'false'.

- -

`<or>`

Evaluates a set of nested conditions, and OR them together. Evaluation is - lazy. An empty <or> evaluates to true.

+ A task is represented as an XML element, where the name of the task is used + as the element name. The attributes and nested elements that a task allows + depend on the task. Below are two example tasks: +

`<os>`

Tests which operating system the build is running on.

+ +This is a log message. +]]> -

`<not>`

Negates a nested condition.

+ Some tasks may contain other tasks. You can find out about how to write + your own tasks here. +

- -

The following file name mappers are available:

- -

`<chain>`

- -

Applies a set of nested file name mappers to file names.

- -

`<flatten>`

- -

Maps all file names to a single directory.

- -

`<prefix>`

- -

Adds a prefix to the front of each file name.

- -

`<map-extension>`

- -

Changes the extension of file names.

- -

-- To unsubscribe, e-mail: For additional commands, e-mail: