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 @@
<section name="Overview">
-<p>
-You define a build process using a <a href="#project">project</a>. 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 <a
href="#targets">targets</a>.
-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.
-</p>
+ <p>
+ You define a build process using a <a href="#project">project</a> 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 <a href="#targets">targets</a>. 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.
+ </p>
-<p>
-A target may <b>depend on</b> 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.
-</p>
+ <p>
+ A target may <b>depend on</b> 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.
+ </p>
-<p>
-You define a target using basic units of work called <a
href="#tasks">tasks</a>.
-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.
-</p>
+ <p>
+ You define a target using basic units of work called <a
href="#tasks">tasks</a>.
+ 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.
+ </p>
+
+ <p>
+ Let's look at a simple example. The project below contains two targets,
+ called <code>compile</code> and <code>build-jar</code>. The
<code>compile</code>
+ target executes the <code>javac</code> task, which, as you probably
+ guessed, compiles up a bunch of Java source files.
+ The <code>build-jar</code> target depends on the <code>compile</code>
target,
+ which means that it will only ever get executed <i>after</i> the
+ <code>compile</code> target has been executed. The
<code>build-jar</code>
+ target executes the <code>jar</code> task, which assembles the compiled
+ class files into a Jar file.
+ </p>
+
+ <source><![CDATA[
+<project version="2.0" default="build-jar">
+
+ <!-- Compile the Java source -->
+ <target name="compile">
+ <javac src-dir="src/java" dest-dir="build/classes"/>
+ </target>
+
+ <!-- Assemble a Jar file -->
+ <target name="build-jar" depends="compile">
+ <jar dest-file="build/myproject.jar">
+ <fileset dir="build/classes"/>
+ </jar>
+ </target>
+</project>
+]]></source>
</section>
<section name="The Project File" anchor="project">
-<p>
-A project file is an XML file that defines a single project. The root
element
-of a project file must be a <code><project></code> element.
-It can take the following attributes:
-</p>
+ <p>
+ A project file is an XML file that defines a single project. The root
element
+ of a project file must be a <code><project></code> element.
+ It can take the following attributes:
+ </p>
-<table>
- <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
- <tr>
- <td>name</td>
- <td>The project name.</td>
- <td>The name of the project file, with the extension removed.</td>
- </tr>
- <tr>
- <td>basedir</td>
- <td>The base directory for the project. The base directory is used
- to resolve all relative file names used in the project file.
- </td>
- <td>The directory containing the project file.</td>
- </tr>
- <tr>
- <td>default</td>
- <td>The name of the default target.</td>
- <td><code>main</code></td>
- </tr>
- <tr>
- <td>version</td>
- <td>The project file format version that the project is written
for.</td>
- <td>None, must be <code>2.0</code></td>
- </tr>
-</table>
+ <table>
+ <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
+ <tr>
+ <td>name</td>
+ <td>The project name.</td>
+ <td>The name of the project file, with the extension
removed.</td>
+ </tr>
+ <tr>
+ <td>basedir</td>
+ <td>The base directory for the project. The base directory is
used
+ to resolve all relative file names used in the project file.
+ </td>
+ <td>The directory containing the project file.</td>
+ </tr>
+ <tr>
+ <td>default</td>
+ <td>The name of the default target.</td>
+ <td><code>main</code></td>
+ </tr>
+ <tr>
+ <td>version</td>
+ <td>The project file format version that the project is written
for.</td>
+ <td>None, must be <code>2.0</code></td>
+ </tr>
+ </table>
-<p>
-A <code><project></code> element can contain the following elements,
-in the order given below:
-</p>
-
-<ul>
-<li><a href="#project-refs">Project references</a></li>
-<li><a href="#init-tasks">Initialization tasks</a></li>
-<li><a href="#targets">Targets</a></li>
-</ul>
+ <p>
+ A <code><project></code> element can contain the following
elements,
+ in the order given below:
+ </p>
+
+ <ul>
+ <li><a href="#project-refs">Project references</a></li>
+ <li><a href="#init-tasks">Initialization tasks</a></li>
+ <li><a href="#targets">Targets</a></li>
+ </ul>
+
+ <p>Below is a simple example, which contains two targets:</p>
+
+<source><![CDATA[
+<project version="2.0" name="some-project" basedir="..">
+
+ <target name="compile">
+ ...
+ </target>
+
+ <target name="tests">
+ ...
+ </target>
+</project>
+]]></source>
<subsection name="Project References" anchor="project-refs">
@@ -104,7 +149,6 @@
<code><i>project-name</i>-><i>target-name</i></code>. Here is a simple
example:</p>
<source><![CDATA[
-
<project version="2.0">
<!-- Reference another project -->
<projectref name="subproject" location="subproject/build.xml"/>
@@ -120,22 +164,27 @@
<subsection name="Initialization Tasks" anchor="init-tasks">
-<p>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 <code><property></code> and data-type instances. An
example:</p>
+ <p>
+ Initialization <a href="#tasks">tasks</a> 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
+ <code><property></code> and data-type instances. The
initialization
+ tasks are executed in the order they appear in the project file.
+ </p>
-<source><![CDATA[
+ <p>Below is an example:</p>
+ <source><![CDATA[
<project version="2.0">
+ <!-- Initialization tasks -->
<property name="some-property" value="some value"/>
- <path id="classpath">
- <fileset dir="lib"/>
- </path>
+ <path id="classpath" ... />
<log>Set classpath to ${classpath}</log>
+ <!-- Targets -->
<target name="main">
- .. do some stuff ..
+ ...
</target>
</project>
@@ -143,123 +192,77 @@
</subsection>
-<subsection name="Targets" anchor="targets">
-
-<p>Targets have a similar format to targets in Ant 1.x, though some of the
-behaviour is different. A <code><target></code> element takes the
-following attributes:</p>
-
-<table>
- <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
- <tr>
- <td>name</td>
- <td>The name of the target.</td>
- <td>Required</td>
- </tr>
- <tr>
- <td>depends</td>
- <td>A comma-separated list of targets that this target depends on.
- This list can contain targets from referenced projects.</td>
- <td>None</td>
- </tr>
-</table>
-
-</subsection>
-
</section>
-<section name="Tasks">
+<section name="Targets" anchor="targets">
<p>
- Listed below are some of the current set of tasks. You can find example
- usages of these tasks in the sample project file
<code>src/make/sample.ant</code>.
+ A target is a list of tasks, contained in a <code><target></code>
+ 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.
</p>
- <h3><code><condition></code></h3>
-
- <p>Sets a property if a particular condition is true. See
- <a href="#Conditions">Conditions</a> for a list of available
conditions.</p>
+ <p>A <code><target></code> element takes the following
attributes:</p>
- <h3><code><fail></code></h3>
- <p>Causes the build to fail.</p>
+ <table>
+ <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
+ <tr>
+ <td>description</td>
+ <td>A description of the target.</td>
+ <td>None</td>
+ </tr>
+ <tr>
+ <td>depends</td>
+ <td>A comma-separated list of targets that this target depends
on.
+ This list can contain targets from referenced projects.</td>
+ <td>None</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>The name of the target.</td>
+ <td>Required</td>
+ </tr>
+ </table>
- <h3><code><if></code></h3>
- <p>Conditionally executes a set of tasks.</p>
+ <p>An example project, with two targets:</p>
- <h3><code><load-properties></code></h3>
- <p>Loads a set of properties from a file.</p>
-
- <h3><code><log></code></h3>
- <p>Writes a log message.</p>
-
- <h3><code><property></code></h3>
- <p>Sets a property.</p>
-
- <h3><code><try-catch></code></h3>
- <p>Runs a set of tasks, with a provided error and clean-up handler.</p>
+<source><![CDATA[
+<project version="2.0" default="jars">
- <h3><code><converter-def></code></h3>
- <p>Register a type converter. These are used when configuring a task
- or data-type from attributes.</p>
+ <target name="compile" description="Compiles the Java source">
+ <javac ... />
+ </target>
- <h3><code><type-def></code></h3>
- <p>Register a task or data-type.</p>
+ <target name="jars" depends="compile" description="Builds the Jar file">
+ <jar ... />
+ </target>
- <h3><code><import></code></h3>
- <p>Register the contents of an antlib.</p>
+</project>
+]]></source>
</section>
-<section name="Conditions">
-
- <p>The following conditions are available </p>
-
- <h3><code><and></code></h3>
- <p>Evaluates a set of nested conditions, and AND them together.
Evaluation is
- lazy. An empty <code><and></code> condition evaluates to true.</p>
-
- <h3><code><available></code></h3>
- <p>Tests if a particular class or resource is available.</p>
-
- <h3><code><file-test></code></h3>
- <p>Tests a file against a set of <a href="vfs.html#File Selectors">file
selectors</a>.</p>
+<section name="Tasks" anchor="tasks">
- <h3><code><is-set></code></h3>
- <p>Tests whether a proeprty is set, and not set to 'false'.</p>
-
- <h3><code><or></code></h3>
- <p>Evaluates a set of nested conditions, and OR them together.
Evaluation is
- lazy. An empty <code><or></code> evaluates to true.</p>
+ <p>
+ 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:
+ </p>
- <h3><code><os></code></h3>
- <p>Tests which operating system the build is running on.</p>
+<source><![CDATA[
+<property name="a-prop" value="some value"/>
+<log>This is a log message.</log>
+]]></source>
- <h3><code><not></code></h3>
- <p>Negates a nested condition.</p>
+ <p>
+ Some tasks may contain other tasks. You can find out about how to write
+ your own tasks <a href="task.html">here</a>.
+ </p>
</section>
-<section name="File Name Mappers">
-
- <p>The following file name mappers are available:</p>
-
- <h3><code><chain></code></h3>
-
- <p>Applies a set of nested file name mappers to file names.</p>
-
- <h3><code><flatten></code></h3>
-
- <p>Maps all file names to a single directory.</p>
-
- <h3><code><prefix></code></h3>
-
- <p>Adds a prefix to the front of each file name.</p>
-
- <h3><code><map-extension></code></h3>
-
- <p>Changes the extension of file names.</p>
-
-</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
