## Antlib

### Description

An antlib file is an xml file with a root element of "antlib". Antlib's elements are ant definition tasks - like Typedef and Taskdef, or any ant task that extends `org.apache.tools.ant.taskdefs.AntlibDefinition`.

A group of tasks and types may be defined together in an antlib file. For example the file sample.xml contains the following:

>     <?xml version="1.0"?>
>     <antlib>
>        <typedef name="if" classname="org.acme.ant.If"/>
>        <typedef name="scriptpathmapper"
>                 classname="org.acme.ant.ScriptPathMapper"
>                 onerror="ignore"/>
>     </antlib>

It defines two types or tasks, if and scriptpathmapper. This antlib file may be used in a build script as follows:

>     <typedef file="sample.xml"/>

The other attributes of `<typedef>` may be used as well. For example, assuming that the sample.xml is in a jar file sample.jar also containing the classes, the following build fragment will define the if and scriptpathmapper tasks/types and place them in the namespace uri samples:/acme.org.

>     <typedef resource="org/acme/ant/sample.xml"
>              uri="samples:/acme.org"/>

The definitions may then be used as follows:

>     <sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org">
>        <sample:scriptpathmapper language="beanshell">
>           some bean shell
>        </sample:scriptpathmapper>
>     </sample:if>

### Antlib namespace

The name space URIs with the pattern antlib:java package are given special treatment.

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 antlib.xml in the package directory in the default classpath.

For example, assuming that the file antcontrib.jar has been placed in the directory ${ant.home}/lib and it contains the resource net/sf/antcontrib/antlib.xml which has all antcontrib's definitions defined, the following build file will automatically load the antcontrib definitions at location HERE:

>     <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>

The requirement that the resource is in the default classpath may be removed in future versions of Ant.

### Current namespace

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 ant:current 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:

>     <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>

### Other examples and comments

Antlibs may make use of other antlibs.

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:

>     <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>

This may be used as follows:

>     <project xmlns:local="localpresets">
>        <typedef file="localpresets.xml" uri="localpresets"/>
>        <local:shellscript>
>           echo "hello world"
>        </local:shellscript>
>     </project>

Copyright © 2003-2004 The Apache Software Foundation. All rights Reserved.