- The xml format is described below in the Antlib + The xml format is described in the + Antlib section.
@@ -81,7 +82,7 @@ are "properties" or "xml". If the value is "properties" the file/resource is a property file contains name to classname pairs. If the value is "xml", the file/resource is an xml file/resource structured according - to Antlib. + to Antlib. The default is "properties" unless the file/resorce name ends with ".xml", in which case the format attribute will have the value "xml". (introduced in ant1.6) @@ -167,29 +168,6 @@ classname="com.acme.ant.RunClock" adapter="org.acme.ant.RunnableAdapter"/> -- <?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"/> --
Copyright © 2001-2003 Apache Software Foundation. All rights Reserved.
diff --git a/docs/manual/CoreTypes/antlib.html b/docs/manual/CoreTypes/antlib.html new file mode 100644 index 000000000..5f2e164a1 --- /dev/null +++ b/docs/manual/CoreTypes/antlib.html @@ -0,0 +1,204 @@ + + + + ++ EXPERIMENTAL: The antlib concept and implementation is experimental + and may be under continual change until Ant1.6 ships. + The contents of this page uses the experimental tasks + <macrodef> and <presetdef> which may not be in + Ant1.6. +
++ An antlib file is an xml file with a root element of "antlib". + Antlib is actually a Sequential task with + special treatment for tasks that are ant definition tasks - like + Typedef + and Taskdef. +
++ 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>
+
+
+ + 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 before Ant 1.6 is released. +
++ 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}"/>
+ <then>
+ <do/>
+ </then>
+ </current:if>
+ </sequential>
+ </macrodef>
+</antlib>
+
+
+ + Althought the primary use of antlibs are ant definitions, one + may use any task or type in an antlib. This should + be treated with caution. +
++ 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 Apache Software +Foundation. All rights Reserved.
+ + + + diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html index 9f6da09b7..3ec9ed6b2 100644 --- a/docs/manual/conceptstypeslist.html +++ b/docs/manual/conceptstypeslist.html @@ -36,10 +36,17 @@ Extension Package