ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From adammurd...@apache.org
Subject cvs commit: jakarta-ant-myrmidon/site/src/xdocs buildfile.xml
Date Thu, 06 Jun 2002 12:53:40 GMT
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>&lt;project&gt;</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>&lt;project&gt;</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>&lt;project&gt;</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>&lt;project&gt;</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>&lt;property&gt;</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>&lt;property&gt;</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>&lt;target&gt;</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>&lt;target&gt;</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>&lt;condition&gt;</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>&lt;target&gt;</code> element takes the following
attributes:</p>
   
  -    <h3><code>&lt;fail&gt;</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>&lt;if&gt;</code></h3>
  -    <p>Conditionally executes a set of tasks.</p>
  +    <p>An example project, with two targets:</p>
   
  -    <h3><code>&lt;load-properties&gt;</code></h3>
  -    <p>Loads a set of properties from a file.</p>
  -
  -    <h3><code>&lt;log&gt;</code></h3>
  -    <p>Writes a log message.</p>
  -
  -    <h3><code>&lt;property&gt;</code></h3>
  -    <p>Sets a property.</p>
  -
  -    <h3><code>&lt;try-catch&gt;</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>&lt;converter-def&gt;</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>&lt;type-def&gt;</code></h3>
  -    <p>Register a task or data-type.</p>
  +    <target name="jars" depends="compile" description="Builds the Jar file">
  +        <jar ... />
  +    </target>
   
  -    <h3><code>&lt;import&gt;</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>&lt;and&gt;</code></h3>
  -    <p>Evaluates a set of nested conditions, and AND them together.  Evaluation is
  -    lazy.  An empty <code>&lt;and&gt;</code> condition evaluates to
true.</p>
  -
  -    <h3><code>&lt;available&gt;</code></h3>
  -    <p>Tests if a particular class or resource is available.</p>
  -
  -    <h3><code>&lt;file-test&gt;</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>&lt;is-set&gt;</code></h3>
  -    <p>Tests whether a proeprty is set, and not set to 'false'.</p>
  -
  -    <h3><code>&lt;or&gt;</code></h3>
  -    <p>Evaluates a set of nested conditions, and OR them together.  Evaluation is
  -    lazy.  An empty <code>&lt;or&gt;</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>&lt;os&gt;</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>&lt;not&gt;</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>&lt;chain&gt;</code></h3>
  -
  -    <p>Applies a set of nested file name mappers to file names.</p>
  -
  -    <h3><code>&lt;flatten&gt;</code></h3>
  -
  -    <p>Maps all file names to a single directory.</p>
  -
  -    <h3><code>&lt;prefix&gt;</code></h3>
  -
  -    <p>Adds a prefix to the front of each file name.</p>
  -
  -    <h3><code>&lt;map-extension&gt;</code></h3>
  -
  -    <p>Changes the extension of file names.</p>
  -
  -</section>
   </body>
   
   </document>
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message