mirror of
https://github.com/apache/ant.git
synced 2025-05-18 05:54:48 +00:00
465 lines
23 KiB
HTML
465 lines
23 KiB
HTML
<!--
|
|
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 id="buildfile">Writing a Simple Buildfile</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 <var>id</var> 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 id="projects">Projects</h3>
|
|
<p>A <em>project</em> has three attributes:</p>
|
|
<table class="attr">
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>name</td>
|
|
<td>the name of the project.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>default</td>
|
|
<td>the default target to use when no target is supplied.</td>
|
|
<td>No; however, <em>since Ant 1.6.0</em>, 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"><code>-projecthelp</code></a> option.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>basedir</td>
|
|
<td>the base directory from which all path calculations are done. A relative path is resolved relative to the
|
|
directory containing the buildfile.
|
|
</td>
|
|
<td>No; defaults to the parent directory of the buildfile, unless overridden by the project's <var>basedir</var> or
|
|
the <code>basedir</code> property</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 <em>targets</em>. A target is a set of <em>tasks</em> 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 <var>default</var> is used.</p>
|
|
|
|
<h3 id="targets">Targets</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
|
|
<em>depends on</em> the compile target. Ant resolves these dependencies.</p>
|
|
<p>It should be noted, however, that Ant's <var>depends</var> attribute only specifies the <em>order</em> 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 id="tasks">Tasks</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>
|
|
|
|
<pre><<i>name</i> <var>attribute1</var>="<i>value1</i>" <var>attribute2</var>="<i>value2</i>" ... /></pre>
|
|
|
|
<p>where <code><i>name</i></code> is the name of the task, <var>attributeN</var> is the attribute name,
|
|
and <code><i>valueN</i></code> 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 can have a <var>name</var> attribute. The value of this attribute will be used in the logging messages
|
|
generated by Ant.</p>
|
|
<p>Tasks can be assigned an <var>id</var> attribute:</p>
|
|
|
|
<pre><<i>taskname</i> <var>id</var>="<i>taskID</i>" ... /></pre>
|
|
|
|
<p>where <code><i>taskname</i></code> is the name of the task, and <code><i>taskID</i></code> 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:</p>
|
|
|
|
<pre>
|
|
<script ... >
|
|
task1.setFoo("bar");
|
|
</script></pre>
|
|
<p>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>
|
|
<p>Note 1: If <q>task1</q> 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 2: Future versions of Ant will most likely <em>not</em> be backward-compatible with this behaviour, since there
|
|
will likely be no task instances at all, only proxies.</p>
|
|
|
|
<h3 id="properties">Properties</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 buildfile.</p>
|
|
|
|
<p>In its most simple form properties are defined in the buildfile
|
|
(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
|
|
<q>${</q> and <q>}</q> in the
|
|
attribute value. For example, if there is a <code>builddir</code>
|
|
property with the value <q>build</q>, then this could be used
|
|
in an attribute like this: <samp>${builddir}/classes</samp>. This
|
|
is resolved at run-time as <samp>build/classes</samp>.</p>
|
|
|
|
<p><em>Since Ant 1.8.0</em>, 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 id="example">Example Buildfile</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. <em>Since Ant 1.6</em>, all tasks can be declared outside
|
|
targets (earlier version only allowed <code><property></code>, <code><typedef></code>
|
|
and <code><taskdef></code>). 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 <code>-projecthelp</code> invocation option to list them as
|
|
public targets with the descriptions; the other target is internal and not listed.</p>
|
|
<p>Finally, for this target to work the source in the <samp>src</samp> subdirectory should be stored in a directory tree
|
|
which matches the package names. Check the <code><javac></code> task for details.</p>
|
|
|
|
<h3 id="filters">Token Filters</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 <strong>must</strong> be of the
|
|
form <code>@<var>token</var>@</code>, where <var>token</var> 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><strong>Note</strong>: If a token with the format <code>@<var>token</var>@</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><strong>Warning</strong>: 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 id="path">Path-like Structures</h3>
|
|
<p>You can specify <code>PATH</code>- and <code>CLASSPATH</code>-type references using both <q>:</q> and <q>;</q> 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 <var>location</var> attribute specifies a single file or directory relative to the project's base directory (or
|
|
an absolute filename), while the <var>path</var> attribute accepts colon- or semicolon-separated lists of
|
|
locations. The <var>path</var> attribute is intended to be used with predefined paths—in any other case, multiple
|
|
elements with <var>location</var> attributes should be preferred.</p>
|
|
<p><em>Since Ant 1.8.2</em> the <var>location</var> attribute can also contain a wildcard in its last path component
|
|
(i.e. it can end in a <q>*</q>) in order to support wildcard <code>CLASSPATH</code>s introduced with Java 6. Ant will
|
|
not expand or evaluate the wildcards and the resulting path may not work as anything else but
|
|
a <code>CLASSPATH</code>—or even as a <code>CLASSPATH</code> for JVM prior to Java 6.</p>
|
|
<p>As a shortcut, the <code><classpath></code> tag
|
|
supports <var>path</var> and
|
|
<var>location</var> 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 collections</a> 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 <samp>${classpath}</samp>, followed by all jar files in
|
|
the <samp>lib</samp> directory, the <samp>classes</samp> directory, all directories named <samp>classes</samp> under
|
|
the <samp>apps</samp> subdirectory of <samp>${build.dir}</samp>, 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 <code><target></code>s, and reference them via their
|
|
<var>id</var> 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. <em>Since Ant 1.8.0</em>, path has an optional <var>cache</var>
|
|
attribute, if it is set to <q>true</q>, the path instance will only scan its nested resource collections once and assume
|
|
it doesn't change during the build anymore (the default for <var>cache</var> still is <q>false</q>). Even if you are
|
|
using the path only in a single task it may improve overall performance to set <var>cache</var> to <q>true</q> 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>
|
|
<p>The shortcuts previously mentioned for <code><classpath></code> are also valid
|
|
for <code><path></code>. For example:</p>
|
|
<pre>
|
|
<path id="base.path">
|
|
<pathelement path="${classpath}"/>
|
|
</path></pre>
|
|
<p>can be written as:</p>
|
|
<pre><path id="base.path" path="${classpath}"/></pre>
|
|
<h4 id="pathshortcut">Path Shortcut</h4>
|
|
<p><em>Since Ant 1.6</em>, there is a shortcut for converting paths to OS specific strings in properties. One can use
|
|
the expression <samp>${toString:<em>pathreference</em>}</samp> 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 id="arg">Command-line Arguments</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 class="attr">
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
<th>Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>value</td>
|
|
<td>a single command-line argument; can contain space characters.</td>
|
|
<td rowspan="5">Exactly one of these.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>file</td>
|
|
<td class="left">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>path</td>
|
|
<td class="left">A string that will be treated as a path-like string as a single command-line argument; you can
|
|
use <q>;</q> or <q>:</q> as path separators and Ant will convert it to the platform's local conventions.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>pathref</td>
|
|
<td class="left"><a href="#references">Reference</a> to a path defined elsewhere. Ant will convert it to the
|
|
platform's local conventions.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>line</td>
|
|
<td class="left">a space-delimited list of command-line arguments.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>prefix</td>
|
|
<td>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>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>suffix</td>
|
|
<td>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>No</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>It is highly recommended to avoid the <var>line</var> 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>
|
|
<pre><arg value="-l -a"/></pre>
|
|
<p>is a single command-line argument containing a space character, <em>not</em> separate options <q>-l</q>
|
|
and <q>-a</q>.</p>
|
|
<pre><arg line="-l -a"/></pre>
|
|
<p>This is a command line with two separate options, <q>-l</q> and <q>-a</q>.</p>
|
|
<pre><arg path="/dir;/dir2:\dir3"/></pre>
|
|
<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 id="references">References</h3>
|
|
|
|
<p>Any project element can be assigned an identifier using its <var>id</var> attribute. In most cases the element can
|
|
subsequently be referenced by specifying the <var>refid</var> 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>
|
|
<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>
|
|
<p>could be rewritten as:</p>
|
|
<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>
|
|
<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 <var>refid</var> 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 <var>refid</var>.</p>
|
|
|
|
<h3 id="external-tasks">Use of external tasks</h3>
|
|
<p>Ant supports a plugin mechanism for using third party tasks. For using them you have to do two steps:</p>
|
|
<ol>
|
|
<li>place their implementation somewhere where Ant can find them.</li>
|
|
<li>declare them.</li>
|
|
</ol>
|
|
<p>Don't add anything to the <code>CLASSPATH</code> 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:</p>
|
|
<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>
|
|
<p>For the declaration there are several ways:</p>
|
|
<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 <samp>properties</samp> 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 an <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 an xml file named <samp>antlib.xml</samp>, 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 <a href="https://ant.apache.org/external.html" target="_top">online</a></li>
|
|
<li>have a look at the external task <a href="https://wiki.apache.org/ant/AntExternalTaskdefs" target="_top">wiki
|
|
page</a></li>
|
|
<li>ask on the <a href="https://ant.apache.org/mail.html#User%20List" target="_top">Ant user</a> list</li>
|
|
<li><a href="tutorial-writing-tasks.html">implement</a> (and share) your own</li>
|
|
</ol>
|
|
|
|
</body>
|
|
</html>
|