| <!DOCTYPE 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 |
| |
| https://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 lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>AntLib</title> |
| </head> |
| |
| <body> |
| <h2 id="antlib">Antlib</h2> |
| |
| <h3>Description</h3> |
| <p> |
| An antlib file is an xml file with a root element of <code>antlib</code>. Antlib's elements |
| are Apache Ant definition tasks—like <a href="../Tasks/taskdef.html">Taskdef</a> or any |
| Ant task that |
| extends <code class="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="../Tasks/typedef.html">Typedef</a></li> |
| <li><a href="../Tasks/taskdef.html">Taskdef</a></li> |
| <li><a href="../Tasks/macrodef.html">Macrodef</a></li> |
| <li><a href="../Tasks/presetdef.html">Presetdef</a></li> |
| <li><a href="../Tasks/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 <samp>sample.xml</samp> contains the following: |
| </p> |
| <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> |
| <p> |
| It defines two types or tasks, <code>if</code> and <code>scriptpathmapper</code>. This |
| antlib file may be used in a build script as follows: |
| </p> |
| <pre><typedef file="sample.xml"/></pre> |
| <p> |
| The other attributes of <code><typedef></code> may be used as well. For example, |
| assuming that the <samp>sample.xml</samp> is in a jar file <samp>sample.jar</samp> also |
| containing the classes, the following build fragment will define the <code>if</code> |
| and <code>scriptpathmapper</code> tasks/types and place them in the namespace |
| uri <code>samples:/acme.org</code>. |
| </p> |
| <pre> |
| <typedef resource="org/acme/ant/sample.xml" |
| uri="samples:/acme.org"/></pre> |
| <p> |
| The definitions may then be used as follows: |
| </p> |
| <pre> |
| <sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org"> |
| <sample:scriptpathmapper language="beanshell"> |
| some bean shell |
| </sample:scriptpathmapper> |
| </sample:if></pre> |
| |
| <h3 id="antlibnamespace">Antlib namespace</h3> |
| <p> |
| The name space URIs with the pattern <code>antlib:<i>java.package</i></code> 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 <samp>antlib.xml</samp> in the package directory in the |
| default classpath. |
| </p> |
| <p> |
| For example, assuming that the file <samp>antcontrib.jar</samp> has been placed in the |
| directory <samp>${ant.home}/lib</samp> and it contains the |
| resource <samp>net/sf/antcontrib/antlib.xml</samp> which has all antcontrib's definitions |
| defined, the following build file will automatically load the antcontrib definitions at |
| location <code>HERE</code>: |
| </p> |
| <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> |
| <p> |
| The requirement that the resource is in the default classpath may be removed in future |
| versions of Ant. |
| </p> |
| <h3 id="loadFromInside">Load antlib from inside of the buildfile</h3> |
| <p> |
| If you want to separate the antlib from your local Ant installation, e.g. because you want |
| to hold that jar in your project's SCM system, you have to specify a classpath, so that |
| Ant could find that jar. The best solution is loading the antlib |
| with <code><taskdef></code>. |
| </p> |
| <pre> |
| <project xmlns:<span style="color:green">antcontrib</span>="<span style="color:red">antlib:net.sf.antcontrib</span>"> |
| <taskdef uri="<span style="color:red">antlib:net.sf.antcontrib</span>" |
| resource="net/sf/antcontrib/antlib.xml" |
| classpath="path/to/ant-contrib.jar"/> |
| |
| <target name="iterate"> |
| <<span style="color:green">antcontrib</span>:for param="file"> |
| <fileset dir="."/> |
| <sequential> |
| <echo message="- @{file}"/> |
| </sequential> |
| </antcontrib:for> |
| </target> |
| </project></pre> |
| <h3 id="currentnamespace">Current namespace</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 namespace |
| URI <code>ant:current</code> 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> |
| <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> |
| <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> |
| <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> |
| <p> |
| This may be used as follows: |
| </p> |
| <pre> |
| <project xmlns:local="localpresets"> |
| <typedef file="localpresets.xml" uri="localpresets"/> |
| <local:shellscript> |
| echo "hello world" |
| </local:shellscript> |
| </project></pre> |
| |
| </body> |
| </html> |
