| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"></meta> |
| <title>AntLib</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </head> |
| |
| <body> |
| <h2><a name="antlib">Antlib</a></h2> |
| <h3>Description</h3> |
| <p> |
| An antlib file is an xml file with a root element of "antlib". |
| Antlib's elements are ant definition tasks - like |
| <a href="../CoreTasks/typedef.html">Typedef</a> |
| and <a href="../CoreTasks/taskdef.html">Taskdef</a>, |
| or any ant task that extends |
| <code>org.apache.tools.ant.taskdefs.AntlibDefinition</code>. |
| </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 in future versions of Ant.</p> |
| </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}"/> |
| <current:then> |
| <current:do/> |
| </current:then> |
| </current:if> |
| </sequential> |
| </macrodef> |
| </antlib> |
| </pre> |
| </blockquote> |
| <h3>Other examples and comments</h3> |
| <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> |
| |
