mirror of
https://github.com/apache/ant.git
synced 2025-05-18 05:54:48 +00:00
3a4980e3c4
find . -type f -exec sed -i "s/http:\/\/www.apache.org\/licenses\/LICENSE-2.0/https:\/\/www.apache.org\/licenses\/LICENSE-2.0/" {} \;
218 lines
8.5 KiB
HTML
218 lines
8.5 KiB
HTML
<!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>
|