| <!-- |
| 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"></meta> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>AntLib</title> |
| </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 |
| |
| and <a href="../CoreTasks/taskdef.html">Taskdef</a>, |
| or any ant task that extends |
| <code>org.apache.tools.ant.taskdefs.AntlibDefinition</code>. |
| </p> |
| <p> |
| The current set of declarations bundled with Ant that do this are: |
| </p> |
| <ol> |
| <li><a href="../CoreTasks/typedef.html">Typedef</a> |
| </li> |
| <li><a href="../CoreTasks/taskdef.html">Taskdef</a> |
| </li> |
| <li><a href="../CoreTasks/macrodef.html">Macrodef</a> |
| </li> |
| <li><a href="../CoreTasks/presetdef.html">Presetdef</a> |
| </li> |
| <li><a href="../OptionalTasks/scriptdef.html">Scriptdef</a> |
| </li> |
| </ol> |
| <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"/> |
| <macrodef name="print"> |
| <attribute name="file"/> |
| <sequential> |
| <concat taskname="print"> |
| <fileset dir="." includes="@{file}"/> |
| </concat> |
| </sequential> |
| </macrodef> |
| </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 <code><typedef></code> 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="loadFromInside">Load antlib from inside of the buildfile</a></h3> |
| <p> |
| If you want to seperate the antlib from your local Ant installation, e.g. because you |
| want to hold that jar in your projects SCM system, you have to specify a classpath, so |
| that Ant could find that jar. The best solution is loading the antlib with <tt><taskdef></tt>. |
| </p> |
| <blockquote> |
| <pre> |
| <project xmlns:<font color="green">antcontrib</font>="<font color="red">antlib:net.sf.antcontrib</font>"> |
| <taskdef uri="<font color="red">antlib:net.sf.antcontrib</font>" |
| resource="net/sf/antcontrib/antlib.xml" |
| classpath="path/to/ant-contrib.jar"/> |
| |
| <target name="iterate"> |
| <<font color="green">antcontrib</font>:for param="file"> |
| <fileset dir="."/> |
| <sequential> |
| <echo message="- @{file}"/> |
| </sequential> |
| </antcontrib:for> |
| </target> |
| </project> |
| </pre> |
| </blockquote> |
| |
| |
| |
| |
| <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 <code><typedef></code> 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 <code><if></code>, the |
| type <code><isallowed></code> and a macro |
| <code><ifallowed></code> 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> |
| <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 <code><typedef></code> 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> |
| |
| |
| |
| </body> |
| </html> |
| |
