| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="stylesheets/style.css"> |
| <title>Writing a Simple Buildfile</title> |
| </head> |
| |
| <body> |
| <h1>Using Apache Ant</h1> |
| <h2><a name="buildfile">Writing a Simple Buildfile</a></h2> |
| <p>Apache Ant's buildfiles are written in XML. Each buildfile contains one project |
| and at least one (default) target. Targets contain task elements. |
| Each task element of the buildfile can have an <code>id</code> attribute and |
| can later be referred to by the value supplied to this. The value has |
| to be unique. (For additional information, see the |
| <a href="#tasks"> Tasks</a> section below.)</p> |
| <h3><a name="projects">Projects</a></h3> |
| <p>A <i>project</i> has three attributes:</p> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">the name of the project.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">default</td> |
| <td valign="top">the default target to use when no target is supplied.</td> |
| <td align="center" valign="top">No; however, <b>since Ant 1.6.0</b>, |
| every project includes an implicit target that contains any and |
| all top-level tasks and/or types. This target will always be |
| executed as part of the project's initialization, even when Ant is |
| run with the <a href="running.html#options">-projecthelp</a> option. |
| </td> |
| </tr> |
| <tr> |
| <td valign="top">basedir</td> |
| <td valign="top">the base directory from which all path calculations are |
| done. This attribute might be overridden by setting |
| the "basedir" |
| property beforehand. When this is done, it must be omitted in the |
| project tag. If neither the attribute nor the property have |
| been set, the parent directory of the buildfile will be used.<br/> |
| A relative path is resolved relative to the directory containing |
| the build file. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| <p>Optionally, a description for the project can be provided as a |
| top-level <code><description></code> element (see the <a |
| href="Types/description.html">description</a> type).</p> |
| |
| <p>Each project defines one or more <i>targets</i>. |
| A target is a set of <i>tasks</i> you want |
| to be executed. When starting Ant, you can select which target(s) you |
| want to have executed. When no target is given, |
| the project's default is used.</p> |
| |
| <h3><a name="targets">Targets</a></h3> |
| <p>A target can depend on other targets. You might have a target for compiling, |
| for example, and a target for creating a distributable. You can only build a |
| distributable when you have compiled first, so the distribute target |
| <i>depends on</i> the compile target. Ant resolves these dependencies.</p> |
| <p>It should be noted, however, that Ant's <code>depends</code> attribute |
| only specifies the <i>order</i> in which targets should be executed - it |
| does not affect whether the target that specifies the dependency(s) gets |
| executed if the dependent target(s) did not (need to) run. |
| </p> |
| |
| <p>More information can be found in the |
| dedicated <a href="targets.html">manual page</a>.</p> |
| |
| <h3><a name="tasks">Tasks</a></h3> |
| <p>A task is a piece of code that can be executed.</p> |
| <p>A task can have multiple attributes (or arguments, if you prefer). The value |
| of an attribute might contain references to a property. These references will be |
| resolved before the task is executed.</p> |
| <p>Tasks have a common structure:</p> |
| <blockquote> |
| <pre><<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /></pre> |
| </blockquote> |
| <p>where <i>name</i> is the name of the task, |
| <i>attributeN</i> is the attribute name, and |
| <i>valueN</i> is the value for this attribute.</p> |
| <p>There is a set of <a href="tasklist.html" target="navFrame">built-in tasks</a>, but it is also very |
| easy to <a href="develop.html#writingowntask">write your own</a>.</p> |
| <p>All tasks share a task name attribute. The value of |
| this attribute will be used in the logging messages generated by |
| Ant.</p> |
| Tasks can be assigned an <code>id</code> attribute: |
| <blockquote> |
| <pre><<i>taskname</i> id="<i>taskID</i>" ... /></pre> |
| </blockquote> |
| where <i>taskname</i> is the name of the task, and <i>taskID</i> is |
| a unique identifier for this task. |
| You can refer to the |
| corresponding task object in scripts or other tasks via this name. |
| For example, in scripts you could do: |
| <blockquote> |
| <pre> |
| <script ... > |
| task1.setFoo("bar"); |
| </script> |
| </pre> |
| </blockquote> |
| to set the <code>foo</code> attribute of this particular task instance. |
| In another task (written in Java), you can access the instance via |
| <code>project.getReference("task1")</code>. |
| <p> |
| Note<sup>1</sup>: If "task1" has not been run yet, then |
| it has not been configured (ie., no attributes have been set), and if it is |
| going to be configured later, anything you've done to the instance may |
| be overwritten. |
| </p> |
| <p> |
| Note<sup>2</sup>: Future versions of Ant will most likely <i>not</i> |
| be backward-compatible with this behaviour, since there will likely be no |
| task instances at all, only proxies. |
| </p> |
| |
| <h3><a name="properties">Properties</a></h3> |
| |
| <p>Properties are an important way to customize a build process or |
| to just provide shortcuts for strings that are used repeatedly |
| inside a build file.</p> |
| |
| <p>In its most simple form properties are defined in the build file |
| (for example by the <a href="Tasks/property.html">property</a> |
| task) or might be set outside Ant. A property has a name and a |
| value; the name is case-sensitive. Properties may be used in the |
| value of task attributes or in the nested text of tasks that support |
| them. This is done by placing the property name between |
| "<code>${</code>" and "<code>}</code>" in the |
| attribute value. For example, if there is a "builddir" |
| property with the value "build", then this could be used |
| in an attribute like this: <code>${builddir}/classes</code>. This |
| is resolved at run-time as <code>build/classes</code>.</p> |
| |
| <p>With Ant 1.8.0 property expansion has become much more powerful |
| than simple key value pairs, more details can be |
| found <a href="properties.html">in the concepts section</a> of this |
| manual.</p> |
| |
| <h3><a name="example">Example Buildfile</a></h3> |
| <pre> |
| <project name="MyProject" default="dist" basedir="."> |
| <description> |
| simple example build file |
| </description> |
| <!-- set global properties for this build --> |
| <property name="src" location="src"/> |
| <property name="build" location="build"/> |
| <property name="dist" location="dist"/> |
| |
| <target name="init"> |
| <!-- Create the time stamp --> |
| <tstamp/> |
| <!-- Create the build directory structure used by compile --> |
| <mkdir dir="${build}"/> |
| </target> |
| |
| <target name="compile" depends="init" |
| description="compile the source " > |
| <!-- Compile the java code from ${src} into ${build} --> |
| <javac srcdir="${src}" destdir="${build}"/> |
| </target> |
| |
| <target name="dist" depends="compile" |
| description="generate the distribution" > |
| <!-- Create the distribution directory --> |
| <mkdir dir="${dist}/lib"/> |
| |
| <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --> |
| <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/> |
| </target> |
| |
| <target name="clean" |
| description="clean up" > |
| <!-- Delete the ${build} and ${dist} directory trees --> |
| <delete dir="${build}"/> |
| <delete dir="${dist}"/> |
| </target> |
| </project> |
| </pre> |
| |
| <p>Notice that we are declaring properties outside any target. As of |
| Ant 1.6 all tasks can be declared outside targets (earlier version |
| only allowed <tt><property></tt>,<tt><typedef></tt> and |
| <tt><taskdef></tt>). When you do this they are evaluated before |
| any targets are executed. Some tasks will generate build failures if |
| they are used outside of targets as they may cause infinite loops |
| otherwise (<code><antcall></code> for example).</p> |
| |
| <p> |
| We have given some targets descriptions; this causes the <tt>projecthelp</tt> |
| invocation option to list them as public targets with the descriptions; the |
| other target is internal and not listed. |
| <p> |
| Finally, for this target to work the source in the <tt>src</tt> subdirectory |
| should be stored in a directory tree which matches the package names. Check the |
| <tt><javac></tt> task for details. |
| |
| <h3><a name="filters">Token Filters</a></h3> |
| <p>A project can have a set of tokens that might be automatically expanded if |
| found when a file is copied, when the filtering-copy behavior is selected in the |
| tasks that support this. These might be set in the buildfile |
| by the <a href="Tasks/filter.html">filter</a> task.</p> |
| <p>Since this can potentially be a very harmful behavior, |
| the tokens in the files <b>must</b> |
| be of the form <code>@</code><i>token</i><code>@</code>, where |
| <i>token</i> is the token name that is set |
| in the <code><filter></code> task. This token syntax matches the syntax of other build systems |
| that perform such filtering and remains sufficiently orthogonal to most |
| programming and scripting languages, as well as with documentation systems.</p> |
| <p>Note: If a token with the format <code>@</code><i>token</i><code>@</code> |
| is found in a file, but no |
| filter is associated with that token, no changes take place; |
| therefore, no escaping |
| method is available - but as long as you choose appropriate names for your |
| tokens, this should not cause problems.</p> |
| <p><b>Warning:</b> If you copy binary files with filtering turned on, you can corrupt the |
| files. This feature should be used with text files <em>only</em>.</p> |
| |
| <h3><a name="path">Path-like Structures</a></h3> |
| <p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type |
| references using both |
| "<code>:</code>" and "<code>;</code>" as separator |
| characters. Ant will |
| convert the separator to the correct character of the current operating |
| system.</p> |
| <p>Wherever path-like values need to be specified, a nested element can |
| be used. This takes the general form of:</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}"/> |
| <pathelement location="lib/helper.jar"/> |
| </classpath> |
| </pre> |
| <p>The <code>location</code> attribute specifies a single file or |
| directory relative to the project's base directory (or an absolute |
| filename), while the <code>path</code> attribute accepts colon- |
| or semicolon-separated lists of locations. The <code>path</code> |
| attribute is intended to be used with predefined paths - in any other |
| case, multiple elements with <code>location</code> attributes should be |
| preferred.</p> |
| <p><em>Since Ant 1.8.2</em> the location attribute can also contain a |
| wildcard in its last path component (i.e. it can end in a |
| "*") in order to support wildcard CLASSPATHs introduced |
| with Java6. Ant will not expand or evaluate the wildcards and the |
| resulting path may not work as anything else but a CLASSPATH - or |
| even as a CLASSPATH for a Java VM prior to Java6.</p> |
| <p>As a shortcut, the <code><classpath></code> tag |
| supports <code>path</code> and |
| <code>location</code> attributes of its own, so:</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}"/> |
| </classpath> |
| </pre> |
| <p>can be abbreviated to:</p> |
| <pre> |
| <classpath path="${classpath}"/> |
| </pre> |
| <p>In addition, one or more |
| <a href="Types/resources.html#collection">Resource Collection</a>s |
| can be specified as nested elements (these must consist of |
| <a href="Types/resources.html#file">file</a>-type resources only). |
| Additionally, it should be noted that although resource collections are |
| processed in the order encountered, certain resource collection types |
| such as <a href="Types/fileset.html">fileset</a>, |
| <a href="Types/dirset.html">dirset</a> and |
| <a href="Types/resources.html#files">files</a> |
| are undefined in terms of order.</p> |
| <pre> |
| <classpath> |
| <pathelement path="${classpath}"/> |
| <fileset dir="lib"> |
| <include name="**/*.jar"/> |
| </fileset> |
| <pathelement location="classes"/> |
| <dirset dir="${build.dir}"> |
| <include name="apps/**/classes"/> |
| <exclude name="apps/**/*Test*"/> |
| </dirset> |
| <filelist refid="third-party_jars"/> |
| </classpath> |
| </pre> |
| <p>This builds a path that holds the value of <code>${classpath}</code>, |
| followed by all jar files in the <code>lib</code> directory, |
| the <code>classes</code> directory, all directories named |
| <code>classes</code> under the <code>apps</code> subdirectory of |
| <code>${build.dir}</code>, except those |
| that have the text <code>Test</code> in their name, and |
| the files specified in the referenced FileList.</p> |
| <p>If you want to use the same path-like structure for several tasks, |
| you can define them with a <code><path></code> element at the |
| same level as <i>target</i>s, and reference them via their |
| <i>id</i> attribute--see <a href="#references">References</a> for an |
| example.</p> |
| |
| <p>By default a path like structure will re-evaluate all nested |
| resource collections whenever it is used, which may lead to |
| unnecessary re-scanning of the filesystem. Since Ant 1.8.0 path has |
| an optional <i>cache</i> attribute, if it is set to true, the path |
| instance will only scan its nested resource collections once and |
| assume it doesn't change during the build anymore (the default |
| for <i>cache</i> still is <i>false</i>). Even if you are using the |
| path only in a single task it may improve overall performance to set |
| <i>cache</i> to <i>true</i> if you are using complex nested |
| constructs.</p> |
| |
| <p>A path-like structure can include a reference to another path-like |
| structure (a path being itself a resource collection) |
| via nested <code><path></code> elements:</p> |
| <pre> |
| <path id="base.path"> |
| <pathelement path="${classpath}"/> |
| <fileset dir="lib"> |
| <include name="**/*.jar"/> |
| </fileset> |
| <pathelement location="classes"/> |
| </path> |
| |
| <path id="tests.path" cache="true"> |
| <path refid="base.path"/> |
| <pathelement location="testclasses"/> |
| </path> |
| </pre> |
| The shortcuts previously mentioned for <code><classpath></code> are also valid for <code><path></code>.For example: |
| <pre> |
| <path id="base.path"> |
| <pathelement path="${classpath}"/> |
| </path> |
| </pre> |
| can be written as: |
| <pre> |
| <path id="base.path" path="${classpath}"/> |
| </pre> |
| |
| <h4><a name="pathshortcut">Path Shortcut</a></h4> |
| <p> |
| In Ant 1.6 a shortcut for converting paths to OS specific strings |
| in properties has been added. One can use the expression |
| ${toString:<em>pathreference</em>} to convert a path element |
| reference to a string that can be used for a path argument. |
| For example: |
| </p> |
| <pre> |
| <path id="lib.path.ref"> |
| <fileset dir="lib" includes="*.jar"/> |
| </path> |
| <javac srcdir="src" destdir="classes"> |
| <compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/> |
| </javac> |
| </pre> |
| |
| |
| <h3><a name="arg">Command-line Arguments</a></h3> |
| <p>Several tasks take arguments that will be passed to another |
| process on the command line. To make it easier to specify arguments |
| that contain space characters, nested <code>arg</code> elements can be used.</p> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">value</td> |
| <td valign="top">a single command-line argument; can contain space |
| characters.</td> |
| <td align="center" rowspan="5">Exactly one of these.</td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">The name of a file as a single command-line |
| argument; will be replaced with the absolute filename of the file.</td> |
| </tr> |
| <tr> |
| <td valign="top">path</td> |
| <td valign="top">A string that will be treated as a path-like |
| string as a single command-line argument; you can use <code>;</code> |
| or <code>:</code> as |
| path separators and Ant will convert it to the platform's local |
| conventions.</td> |
| </tr> |
| <tr> |
| <td valign="top">pathref</td> |
| <td valign="top"><a href="#references">Reference</a> to a path |
| defined elsewhere. Ant will convert it to the platform's local |
| conventions.</td> |
| </tr> |
| <tr> |
| <td valign="top">line</td> |
| <td valign="top">a space-delimited list of command-line arguments.</td> |
| </tr> |
| <tr> |
| <td valign="top">prefix</td> |
| <td valign="top">A fixed string to be placed in front of the |
| argument. In the case of a line broken into parts, it will be |
| placed in front of every part. <em>Since Ant 1.8.</em></td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">suffix</td> |
| <td valign="top">A fixed string to be placed immediately after the |
| argument. In the case of a line broken into parts, it will be |
| placed after every part. <em>Since Ant 1.8.</em></td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <p>It is highly recommended to avoid the <code>line</code> version |
| when possible. Ant will try to split the command line in a way |
| similar to what a (Unix) shell would do, but may create something that |
| is very different from what you expect under some circumstances.</p> |
| |
| <h4>Examples</h4> |
| <blockquote><pre> |
| <arg value="-l -a"/> |
| </pre></blockquote> |
| <p>is a single command-line argument containing a space character, |
| <i>not</i> separate commands "-l" and "-a".</p> |
| <blockquote><pre> |
| <arg line="-l -a"/> |
| </pre></blockquote> |
| <p>This is a command line with two separate arguments, "-l" and "-a".</p> |
| <blockquote><pre> |
| <arg path="/dir;/dir2:\dir3"/> |
| </pre></blockquote> |
| <p>is a single command-line argument with the value |
| <code>\dir;\dir2;\dir3</code> on DOS-based systems and |
| <code>/dir:/dir2:/dir3</code> on Unix-like systems.</p> |
| |
| <h3><a name="references">References</a></h3> |
| |
| <p>Any project element can be assigned an identifier using its |
| <code>id</code> attribute. In most cases the element can subsequently |
| be referenced by specifying the <code>refid</code> attribute on an |
| element of the same type. This can be useful if you are going to |
| replicate the same snippet of XML over and over again--using a |
| <code><classpath></code> structure more than once, for example.</p> |
| <p>The following example:</p> |
| <blockquote><pre> |
| <project ... > |
| <target ... > |
| <rmic ...> |
| <classpath> |
| <pathelement location="lib/"/> |
| <pathelement path="${java.class.path}/"/> |
| <pathelement path="${additional.path}"/> |
| </classpath> |
| </rmic> |
| </target> |
| |
| <target ... > |
| <javac ...> |
| <classpath> |
| <pathelement location="lib/"/> |
| <pathelement path="${java.class.path}/"/> |
| <pathelement path="${additional.path}"/> |
| </classpath> |
| </javac> |
| </target> |
| </project> |
| </pre></blockquote> |
| <p>could be rewritten as:</p> |
| <blockquote><pre> |
| <project ... > |
| <path id="project.class.path"> |
| <pathelement location="lib/"/> |
| <pathelement path="${java.class.path}/"/> |
| <pathelement path="${additional.path}"/> |
| </path> |
| |
| <target ... > |
| <rmic ...> |
| <classpath refid="project.class.path"/> |
| </rmic> |
| </target> |
| |
| <target ... > |
| <javac ...> |
| <classpath refid="project.class.path"/> |
| </javac> |
| </target> |
| </project> |
| </pre></blockquote> |
| <p>All tasks that use nested elements for |
| <a href="Types/patternset.html">PatternSet</a>s, |
| <a href="Types/fileset.html">FileSet</a>s, |
| <a href="Types/zipfileset.html">ZipFileSet</a>s or |
| <a href="#path">path-like structures</a> accept references to these structures |
| as shown in the examples. Using <code>refid</code> on a task will ordinarily |
| have the same effect (referencing a task already declared), but the user |
| should be aware that the interpretation of this attribute is dependent on the |
| implementation of the element upon which it is specified. Some tasks (the |
| <a href="Tasks/property.html">property</a> task is a handy example) |
| deliberately assign a different meaning to <code>refid</code>.</p> |
| |
| |
| <h3><a name="external-tasks">Use of external tasks</a></h3> |
| Ant supports a plugin mechanism for using third party tasks. For using them you |
| have to do two steps: |
| <ol> |
| <li>place their implementation somewhere where Ant can find them</li> |
| <li>declare them.</li> |
| </ol> |
| Don't add anything to the CLASSPATH environment variable - this is often the |
| reason for very obscure errors. Use Ant's own <a href="install.html#optionalTasks">mechanisms</a> |
| for adding libraries: |
| <ul> |
| <li>via command line argument <code>-lib</code></li> |
| <li>adding to <code>${user.home}/.ant/lib</code></li> |
| <li>adding to <code>${ant.home}/lib</code></li> |
| </ul> |
| For the declaration there are several ways: |
| <ul> |
| <li>declare a single task per using instruction using |
| <code><<a href="Tasks/taskdef.html">taskdef</a> name="taskname" |
| classname="ImplementationClass"/></code> |
| <br> |
| <code><taskdef name="for" classname="net.sf.antcontrib.logic.For" /> |
| <for ... /></code> |
| </li> |
| <li>declare a bundle of tasks using a properties-file holding these |
| taskname-ImplementationClass-pairs and <code><taskdef></code> |
| <br> |
| <code><taskdef resource="net/sf/antcontrib/antcontrib.properties" /> |
| <for ... /></code> |
| </li> |
| <li>declare a bundle of tasks using a <a href="Types/antlib.html">xml-file</a> holding these |
| taskname-ImplementationClass-pairs and <code><taskdef></code> |
| <br> |
| <code><taskdef resource="net/sf/antcontrib/antlib.xml" /> |
| <for ... /></code> |
| </li> |
| <li>declare a bundle of tasks using a xml-file named antlib.xml, XML-namespace and |
| <a href="Types/antlib.html#antlibnamespace"><code>antlib:</code> protocol handler</a> |
| <br> |
| <code><project xmlns:ac="antlib:net.sf.antcontrib"/> |
| <ac:for ... /></code> |
| </li> |
| </ul> |
| |
| If you need a special function, you should |
| <ol> |
| <li>have a look at this manual, because Ant provides lot of tasks</li> |
| <li>have a look at the external task page in the <a href="../external.html">manual</a> |
| (or better <a href="http://ant.apache.org/external.html">online</a>)</li> |
| <li>have a look at the external task <a href="http://wiki.apache.org/ant/AntExternalTaskdefs">wiki |
| page</a></li> |
| <li>ask on the <a href="http://ant.apache.org/mail.html#User%20List">Ant user</a> list</li> |
| <li><a href="tutorial-writing-tasks.html">implement </a>(and share) your own</li> |
| </ol> |
| |
| </body> |
| </html> |