|
|
|
@@ -0,0 +1,204 @@ |
|
|
|
<html> |
|
|
|
|
|
|
|
<head> |
|
|
|
<meta http-equiv="Content-Language" content="en-us"></meta> |
|
|
|
<title>AntLib</title> |
|
|
|
</head> |
|
|
|
|
|
|
|
<body> |
|
|
|
<h2><a name="antlib">Antlib</a></h2> |
|
|
|
<p> |
|
|
|
<i>EXPERIMENTAL:</i> The antlib concept and implementation is experimental |
|
|
|
and may be under continual change until Ant1.6 ships. |
|
|
|
The contents of this page uses the experimental tasks |
|
|
|
<macrodef> and <presetdef> which may not be in |
|
|
|
Ant1.6. |
|
|
|
</p> |
|
|
|
<h3>Description</h3> |
|
|
|
<p> |
|
|
|
An antlib file is an xml file with a root element of "antlib". |
|
|
|
Antlib is actually a <a href="sequential.html">Sequential</a> task with |
|
|
|
special treatment for tasks that are ant definition tasks - like |
|
|
|
<a href="../CoreTasks/typedef.html">Typedef</a> |
|
|
|
and <a href="../CoreTasks/taskdef.html">Taskdef</a>. |
|
|
|
</p> |
|
|
|
<p> |
|
|
|
A group of tasks and types may be defined together in an antlib |
|
|
|
file. For example the file <i>sample.xml</i> contains the following: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<?xml version="1.0"?> |
|
|
|
<antlib> |
|
|
|
<typedef name="if" classname="org.acme.ant.If"/> |
|
|
|
<typedef name="scriptpathmapper" |
|
|
|
classname="org.acme.ant.ScriptPathMapper" |
|
|
|
onerror="ignore"/> |
|
|
|
</antlib> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<p> |
|
|
|
It defines two types or tasks, <i>if</i> and <i>scriptpathmapper</i>. |
|
|
|
This antlib file may be used in a build script as follows: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<typedef file="sample.xml"/> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<p> |
|
|
|
The other attributes of <typedef> may be used as well. |
|
|
|
For example, assuming that the <i>sample.xml</i> is in a jar |
|
|
|
file <i>sample.jar</i> also containing the classes, the |
|
|
|
following build fragment will define the <i>if</i> and <i>scriptpathmapper</i> |
|
|
|
tasks/types and place them in the namespace uri <i>samples:/acme.org</i>. |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<typedef resource="org/acme/ant/sample.xml" |
|
|
|
uri="samples:/acme.org"/> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<p> |
|
|
|
The definitions may then be used as follows: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org"> |
|
|
|
<sample:scriptpathmapper language="beanshell"> |
|
|
|
some bean shell |
|
|
|
</sample:scriptpathmapper> |
|
|
|
</sample:if> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<h3><a name="antlibnamespace">Antlib namespace</a></h3> |
|
|
|
<p> |
|
|
|
The name space URIs with the pattern <b>antlib:<i>java package</i></b> |
|
|
|
are given special treatment. |
|
|
|
</p> |
|
|
|
<p> |
|
|
|
When ant encounters a element with a namespace URI with this pattern, it |
|
|
|
will check to see if there is a resource of the name <i>antlib.xml</i> in |
|
|
|
the package directory in the default classpath. |
|
|
|
</p> |
|
|
|
<p> |
|
|
|
For example, assuming that the file <i>antcontrib.jar</i> has been placed |
|
|
|
in the directory <i>${ant.home}/lib</i> and it contains the resource |
|
|
|
<i>net/sf/antcontrib/antlib.xml</i> which has all antcontrib's definitions |
|
|
|
defined, the following build file will automatically load the antcontrib |
|
|
|
definitions at location <i>HERE</i>: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<project default="deletetest" xmlns:antcontrib="antlib:net.sf.antcontrib"> |
|
|
|
<macrodef name="showdir"> |
|
|
|
<attribute name="dir"/> |
|
|
|
<sequential> |
|
|
|
<antcontrib:shellscript shell="bash"> <!-- HERE --> |
|
|
|
ls -Rl ${dir} |
|
|
|
</antcontrib:shellscript> |
|
|
|
</sequential> |
|
|
|
</macrodef> |
|
|
|
|
|
|
|
<target name="deletetest"> |
|
|
|
<delete dir="a" quiet="yes"/> |
|
|
|
<mkdir dir="a/b"/> |
|
|
|
<touch file="a/a.txt"/> |
|
|
|
<touch file="a/b/b.txt"/> |
|
|
|
<delete> |
|
|
|
<fileset dir="a"/> |
|
|
|
</delete> |
|
|
|
<showdir dir="a"/> |
|
|
|
</target> |
|
|
|
</project> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<p> |
|
|
|
The requirement that the resource is in the default classpath |
|
|
|
may be removed before Ant 1.6 is released. |
|
|
|
</p> |
|
|
|
<h3><a name="currentnamespace">Current namespace</a></h3> |
|
|
|
<p> |
|
|
|
Definitions defined in antlibs may be used in antlibs. However |
|
|
|
the namespace that definitions are placed in are dependent on |
|
|
|
the <typedef> that uses the antlib. To deal with this |
|
|
|
problem, the definitions are placed in the namepace URI <i>ant:current</i> |
|
|
|
for the duration of the antlib execution. |
|
|
|
For example the following antlib defines the task <if>, the |
|
|
|
type <isallowed> and a macro |
|
|
|
<ifallowed> that makes use of the task and type: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<antlib xmlns:current="ant:current"> |
|
|
|
<taskdef name="if" classname="org.acme.ant.If"/> |
|
|
|
<typedef name="isallowed" classname="org.acme.ant.Isallowed"/> |
|
|
|
<macrodef name="ifallowed"> |
|
|
|
<attribute name="action"/> |
|
|
|
<element name="do"/> |
|
|
|
<sequential> |
|
|
|
<current:if> |
|
|
|
<current:isallowed test="${action}"/> |
|
|
|
<then> |
|
|
|
<do/> |
|
|
|
</then> |
|
|
|
</current:if> |
|
|
|
</sequential> |
|
|
|
</macrodef> |
|
|
|
</antlib> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<h3>Other examples and comments</h3> |
|
|
|
<p> |
|
|
|
Althought the primary use of antlibs are ant definitions, one |
|
|
|
may use any task or type in an antlib. This should |
|
|
|
be treated with caution. |
|
|
|
</p> |
|
|
|
<p> |
|
|
|
Antlibs may make use of other antlibs. |
|
|
|
</p> |
|
|
|
<p> |
|
|
|
As the names defined in the antlib are in the namespace uri as |
|
|
|
specified by the calling <typedef> or by automatic element |
|
|
|
resolution, one may reuse names from core ant types and tasks, |
|
|
|
provided the caller uses a namespace uri. For example, the |
|
|
|
following antlib may be used to define defaults for various |
|
|
|
tasks: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<antlib xmlns:antcontrib="antlib:net.sf.antcontrib"> |
|
|
|
<presetdef name="javac"> |
|
|
|
<javac deprecation="${deprecation}" |
|
|
|
debug="${debug}"/> |
|
|
|
</presetdef> |
|
|
|
<presetdef name="delete"> |
|
|
|
<delete quiet="yes"/> |
|
|
|
</presetdef> |
|
|
|
<presetdef name="shellscript"> |
|
|
|
<antcontrib:shellscript shell="bash"/> |
|
|
|
</presetdef> |
|
|
|
</antlib> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
<p> |
|
|
|
This may be used as follows: |
|
|
|
</p> |
|
|
|
<blockquote> |
|
|
|
<pre> |
|
|
|
<project xmlns:local="localpresets"> |
|
|
|
<typedef file="localpresets.xml" uri="localpresets"/> |
|
|
|
<local:shellscript> |
|
|
|
echo "hello world" |
|
|
|
</local:shellscript> |
|
|
|
</project> |
|
|
|
</pre> |
|
|
|
</blockquote> |
|
|
|
|
|
|
|
<hr> |
|
|
|
<p align="center">Copyright © 2003 Apache Software |
|
|
|
Foundation. All rights Reserved.</p> |
|
|
|
|
|
|
|
</body> |
|
|
|
</html> |
|
|
|
|
Peter Reilly