| 1 |
<!DOCTYPE html> |
| 2 |
<!-- |
| 3 |
Licensed to the Apache Software Foundation (ASF) under one or more |
| 4 |
contributor license agreements. See the NOTICE file distributed with |
| 5 |
this work for additional information regarding copyright ownership. |
| 6 |
The ASF licenses this file to You under the Apache License, Version 2.0 |
| 7 |
(the "License"); you may not use this file except in compliance with |
| 8 |
the License. You may obtain a copy of the License at |
| 9 |
|
| 10 |
https://www.apache.org/licenses/LICENSE-2.0 |
| 11 |
|
| 12 |
Unless required by applicable law or agreed to in writing, software |
| 13 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 14 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 |
See the License for the specific language governing permissions and |
| 16 |
limitations under the License. |
| 17 |
--> |
| 18 |
<html lang="en"> |
| 19 |
|
| 20 |
<head> |
| 21 |
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| 22 |
<title>AntLib</title> |
| 23 |
</head> |
| 24 |
|
| 25 |
<body> |
| 26 |
<h2 id="antlib">Antlib</h2> |
| 27 |
|
| 28 |
<h3>Description</h3> |
| 29 |
<p> |
| 30 |
An antlib file is an xml file with a root element of <code>antlib</code>. Antlib's elements |
| 31 |
are Apache Ant definition tasks—like <a href="../Tasks/taskdef.html">Taskdef</a> or any |
| 32 |
Ant task that |
| 33 |
extends <code class="code">org.apache.tools.ant.taskdefs.AntlibDefinition</code>. |
| 34 |
</p> |
| 35 |
<p> |
| 36 |
The current set of declarations bundled with Ant that do this are: |
| 37 |
</p> |
| 38 |
<ol> |
| 39 |
<li><a href="../Tasks/typedef.html">Typedef</a></li> |
| 40 |
<li><a href="../Tasks/taskdef.html">Taskdef</a></li> |
| 41 |
<li><a href="../Tasks/macrodef.html">Macrodef</a></li> |
| 42 |
<li><a href="../Tasks/presetdef.html">Presetdef</a></li> |
| 43 |
<li><a href="../Tasks/scriptdef.html">Scriptdef</a></li> |
| 44 |
</ol> |
| 45 |
<p> |
| 46 |
A group of tasks and types may be defined together in an antlib file. For example the |
| 47 |
file <samp>sample.xml</samp> contains the following: |
| 48 |
</p> |
| 49 |
<pre> |
| 50 |
<?xml version="1.0"?> |
| 51 |
<antlib> |
| 52 |
<typedef name="if" classname="org.acme.ant.If"/> |
| 53 |
<typedef name="scriptpathmapper" |
| 54 |
classname="org.acme.ant.ScriptPathMapper" |
| 55 |
onerror="ignore"/> |
| 56 |
<macrodef name="print"> |
| 57 |
<attribute name="file"/> |
| 58 |
<sequential> |
| 59 |
<concat taskname="print"> |
| 60 |
<fileset dir="." includes="@{file}"/> |
| 61 |
</concat> |
| 62 |
</sequential> |
| 63 |
</macrodef> |
| 64 |
</antlib></pre> |
| 65 |
<p> |
| 66 |
It defines two types or tasks, <code>if</code> and <code>scriptpathmapper</code>. This |
| 67 |
antlib file may be used in a build script as follows: |
| 68 |
</p> |
| 69 |
<pre><typedef file="sample.xml"/></pre> |
| 70 |
<p> |
| 71 |
The other attributes of <code><typedef></code> may be used as well. For example, |
| 72 |
assuming that the <samp>sample.xml</samp> is in a jar file <samp>sample.jar</samp> also |
| 73 |
containing the classes, the following build fragment will define the <code>if</code> |
| 74 |
and <code>scriptpathmapper</code> tasks/types and place them in the namespace |
| 75 |
uri <code>samples:/acme.org</code>. |
| 76 |
</p> |
| 77 |
<pre> |
| 78 |
<typedef resource="org/acme/ant/sample.xml" |
| 79 |
uri="samples:/acme.org"/></pre> |
| 80 |
<p> |
| 81 |
The definitions may then be used as follows: |
| 82 |
</p> |
| 83 |
<pre> |
| 84 |
<sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org"> |
| 85 |
<sample:scriptpathmapper language="beanshell"> |
| 86 |
some bean shell |
| 87 |
</sample:scriptpathmapper> |
| 88 |
</sample:if></pre> |
| 89 |
|
| 90 |
<h3 id="antlibnamespace">Antlib namespace</h3> |
| 91 |
<p> |
| 92 |
The name space URIs with the pattern <code>antlib:<i>java.package</i></code> are given |
| 93 |
special treatment. |
| 94 |
</p> |
| 95 |
<p> |
| 96 |
When Ant encounters a element with a namespace URI with this pattern, it will check to see |
| 97 |
if there is a resource of the name <samp>antlib.xml</samp> in the package directory in the |
| 98 |
default classpath. |
| 99 |
</p> |
| 100 |
<p> |
| 101 |
For example, assuming that the file <samp>antcontrib.jar</samp> has been placed in the |
| 102 |
directory <samp>${ant.home}/lib</samp> and it contains the |
| 103 |
resource <samp>net/sf/antcontrib/antlib.xml</samp> which has all antcontrib's definitions |
| 104 |
defined, the following build file will automatically load the antcontrib definitions at |
| 105 |
location <code>HERE</code>: |
| 106 |
</p> |
| 107 |
<pre> |
| 108 |
<project default="deletetest" xmlns:antcontrib="antlib:net.sf.antcontrib"> |
| 109 |
<macrodef name="showdir"> |
| 110 |
<attribute name="dir"/> |
| 111 |
<sequential> |
| 112 |
<antcontrib:shellscript shell="bash"> <!-- HERE --> |
| 113 |
ls -Rl @{dir} |
| 114 |
</antcontrib:shellscript> |
| 115 |
</sequential> |
| 116 |
</macrodef> |
| 117 |
|
| 118 |
<target name="deletetest"> |
| 119 |
<delete dir="a" quiet="yes"/> |
| 120 |
<mkdir dir="a/b"/> |
| 121 |
<touch file="a/a.txt"/> |
| 122 |
<touch file="a/b/b.txt"/> |
| 123 |
<delete> |
| 124 |
<fileset dir="a"/> |
| 125 |
</delete> |
| 126 |
<showdir dir="a"/> |
| 127 |
</target> |
| 128 |
</project></pre> |
| 129 |
<p> |
| 130 |
The requirement that the resource is in the default classpath may be removed in future |
| 131 |
versions of Ant. |
| 132 |
</p> |
| 133 |
<h3 id="loadFromInside">Load antlib from inside of the buildfile</h3> |
| 134 |
<p> |
| 135 |
If you want to separate the antlib from your local Ant installation, e.g. because you want |
| 136 |
to hold that jar in your project's SCM system, you have to specify a classpath, so that |
| 137 |
Ant could find that jar. The best solution is loading the antlib |
| 138 |
with <code><taskdef></code>. |
| 139 |
</p> |
| 140 |
<pre> |
| 141 |
<project xmlns:<span style="color:green">antcontrib</span>="<span style="color:red">antlib:net.sf.antcontrib</span>"> |
| 142 |
<taskdef uri="<span style="color:red">antlib:net.sf.antcontrib</span>" |
| 143 |
resource="net/sf/antcontrib/antlib.xml" |
| 144 |
classpath="path/to/ant-contrib.jar"/> |
| 145 |
|
| 146 |
<target name="iterate"> |
| 147 |
<<span style="color:green">antcontrib</span>:for param="file"> |
| 148 |
<fileset dir="."/> |
| 149 |
<sequential> |
| 150 |
<echo message="- @{file}"/> |
| 151 |
</sequential> |
| 152 |
</antcontrib:for> |
| 153 |
</target> |
| 154 |
</project></pre> |
| 155 |
<h3 id="currentnamespace">Current namespace</h3> |
| 156 |
<p> |
| 157 |
Definitions defined in antlibs may be used in antlibs. However, the namespace that |
| 158 |
definitions are placed in are dependent on the <code><typedef></code> that uses the |
| 159 |
antlib. To deal with this problem, the definitions are placed in the namespace |
| 160 |
URI <code>ant:current</code> for the duration of the antlib execution. For example, the |
| 161 |
following antlib defines the task <code><if></code>, the |
| 162 |
type <code><isallowed></code> and a macro <code><ifallowed></code> that makes |
| 163 |
use of the task and type: |
| 164 |
</p> |
| 165 |
<pre> |
| 166 |
<antlib xmlns:current="ant:current"> |
| 167 |
<taskdef name="if" classname="org.acme.ant.If"/> |
| 168 |
<typedef name="isallowed" classname="org.acme.ant.Isallowed"/> |
| 169 |
<macrodef name="ifallowed"> |
| 170 |
<attribute name="action"/> |
| 171 |
<element name="do"/> |
| 172 |
<sequential> |
| 173 |
<current:if> |
| 174 |
<current:isallowed test="@{action}"/> |
| 175 |
<current:then> |
| 176 |
<do/> |
| 177 |
</current:then> |
| 178 |
</current:if> |
| 179 |
</sequential> |
| 180 |
</macrodef> |
| 181 |
</antlib></pre> |
| 182 |
<h3>Other examples and comments</h3> |
| 183 |
<p> |
| 184 |
Antlibs may make use of other antlibs. |
| 185 |
</p> |
| 186 |
<p> |
| 187 |
As the names defined in the antlib are in the namespace URI as specified by the |
| 188 |
calling <code><typedef></code> or by automatic element resolution, one may reuse |
| 189 |
names from core Ant types and tasks, provided the caller uses a namespace URI. For |
| 190 |
example, the following antlib may be used to define defaults for various tasks: |
| 191 |
</p> |
| 192 |
<pre> |
| 193 |
<antlib xmlns:antcontrib="antlib:net.sf.antcontrib"> |
| 194 |
<presetdef name="javac"> |
| 195 |
<javac deprecation="${deprecation}" |
| 196 |
debug="${debug}"/> |
| 197 |
</presetdef> |
| 198 |
<presetdef name="delete"> |
| 199 |
<delete quiet="yes"/> |
| 200 |
</presetdef> |
| 201 |
<presetdef name="shellscript"> |
| 202 |
<antcontrib:shellscript shell="bash"/> |
| 203 |
</presetdef> |
| 204 |
</antlib></pre> |
| 205 |
<p> |
| 206 |
This may be used as follows: |
| 207 |
</p> |
| 208 |
<pre> |
| 209 |
<project xmlns:local="localpresets"> |
| 210 |
<typedef file="localpresets.xml" uri="localpresets"/> |
| 211 |
<local:shellscript> |
| 212 |
echo "hello world" |
| 213 |
</local:shellscript> |
| 214 |
</project></pre> |
| 215 |
|
| 216 |
</body> |
| 217 |
</html> |