-
|
- ||
| -#* *##if ($node.name().equals("task")) -#* Use description from merged XML if available, else javadoc comment *# -#* *##if ($node.external.description) - -#* *#$context.applyTemplates("external/description") -#* *##else - -#* *#$context.applyTemplates("long-description") -#* *##end -#* *#$context.applyTemplates("short-description") -#* *#$context.applyTemplates("attribute/description") -#* *#$context.applyTemplates("element/description") -#* *#$context.applyTemplates("structure/attribute-groups") -#* *#$context.applyTemplates("structure/elements") -#* *#$context.applyTemplates("external/section") -#* *##end - | -||
|
- - |
- ||
|
-
- Copyright © 2000-2005, Apache Software Foundation
-
- |
-
- $node.value().trim() - |
-#* *#$context.applyTemplates("*") - |
- |
-#* *#$context.applyTemplates("*") - |
| - - $attrib.name ($attrib.type) - |
- $node.description.toString().trim() -#* *#$context.applyTemplates("*") - |
|
- |
- $attrib.name -
--
- $context.applyTemplates("item")
-
| - - #if ( $attrib.anchor ) - #set( $anchor = $attrib.anchor ) - #else - #set( $anchor = $attrib.name ) - #end - - $attrib.name - |
- $context.applyTemplates("*") - |
| - - #if ( $attrib.anchor ) - #set( $anchor = $attrib.anchor ) - #else - #set( $anchor = $attrib.name ) - #end - - $attrib.name - |
| - $context.applyTemplates("*") - |
-
-
-
-#end
-
-
-#match("table")
-
- 
- |
-
-
- |
-
-
- |
-
|
-
- |
-
- $toolbox.htmlescape.getText( $node.value() )- |
-
-
- |
-
|
-
- |
-
-
- |
-
-
- |
-
" + category + "
"); - - sb.append("- ");
-
- String[] tasks = (String[]) data.get(category);
-
- for (int j=0; j < tasks.length; j++) {
- taskCount++;
- String task = tasks[j];
- sb.append("
- "); - sb.append("" + task + ""); - sb.append(" "); - } - - sb.append("
Sets a property if a certain condition holds true - this is a -generalization of Available and Uptodate.
-If the condition holds true, the property value is set to true by
-default; otherwise, the property is not set. You can set the value to
-something other than the default by specifying the value
-attribute.
Conditions are specified as nested elements, -you must specify exactly one condition.
- -- <condition property="javamail.complete"> - <and> - <available classname="javax.activation.DataHandler" /> - <available classname="javax.mail.Transport" /> - </and> - </condition> --
sets the property javamail.complete if both the
-JavaBeans Activation Framework and JavaMail are available in the
-classpath.
- <condition property="isMacOsButNotMacOsX"> - <and> - <os family="mac" /> - <not> - <os family="unix" /> - </not> - </and> - </condition> --
sets the property isMacOsButNotMacOsX if the current
-operating system is MacOS, but not MacOS X - which Ant considers to be
-in the Unix family as well.
- <condition property="isSunOSonSparc"> - <os name="SunOS" arch="sparc" /> - </condition> --
sets the property isSunOSonSparc if the current
-operating system is SunOS and if it is running on a sparc architecture.
Compiles a Java source tree.
- -The source and destination directory will be recursively scanned for Java -source files to compile. Only Java files that have no corresponding class file -or where the class file is older than the java file will be compiled.
- -Note: Ant uses only the names of the source and class files to find -the classes that need a rebuild. It will not scan the source and therefor -will have no knowledge about nested classes, classes that are named different -from the source file and so on.
- -The directory structure of the source tree should follow the package -hierarchy.
- -It is possible to refine the set of files that are being compiled/copied. -This can be done with the includes, includesfile, excludes, excludesfile and defaultexcludes -attributes. With the includes or includesfile attribute you specify the files you want to -have included by using patterns. The exclude or excludesfile attribute is used to specify -the files you want to have excluded. This is also done with patterns. And -finally with the defaultexcludes attribute, you can specify whether you -want to use default exclusions or not. See the section on directory based tasks, on how the -inclusion/exclusion of files works, and how to write patterns.
- -It is possible to use different compilers. This can be selected with the -"build.compiler" property or the compiler attribute. Here are the choices:-
--
-
- classic (the standard compiler of JDK 1.1/1.2) - javac1.1 and - javac1.2 can be used as aliases -
- modern (the standard compiler of JDK 1.3/1.4) - javac1.3 and - javac1.4 can be used as aliases -
- jikes (the Jikes - compiler) -
- jvc (the Command-Line Compiler from Microsoft's SDK for Java / - Visual J++) - microsoft can be used as an alias -
- kjc (the kopi - compiler) -
- gcj (the gcj compiler from gcc) -
- sj (Symantec java compiler) - symantec can be used as an alias -
- extJavac (run either modern or classic in a JVM of its own) -
For JDK 1.1/1.2, classic is the default. For JDK 1.3/1.4, modern is the default. -If you wish to use a different compiler interface than those -supplied, write a class that implements the CompilerAdapter interface -(package org.apache.tools.ant.taskdefs.compilers). Supply the full -classname in the "build.compiler" property.
- -The fork attribute overrides the build.compiler setting and expects -a JDK1.1 or higher to be set in java.home.
- -This task will drop all entries that point to non-existent -files/directories from the CLASSPATH it passes to the compiler.
- -Windows Note:When the modern compiler is used -in unforked mode on Windows, it locks up the files present in the -classpath of the <javac> task, and does not release them. The side -effect of this is that you will not be able to delete or move -those files later on in the build. The workaround is to fork when -invoking the compiler.
- - <javac srcdir="${src}"
- destdir="${build}"
- classpath="xyz.jar"
- debug="on"
- />
-compiles all .java files under the ${src}
-directory, and stores
-the .class files in the ${build} directory.
-The classpath used contains xyz.jar, and debug information is on.
<javac srcdir="${src}"
- destdir="${build}"
- fork="true"
- />
-compiles all .java files under the ${src}
-directory, and stores the .class files in the
-${build} directory. This will fork off the javac
-compiler using the default javac executable.
<javac srcdir="${src}"
- destdir="${build}"
- fork="java$$javac.exe"
- />
-compiles all .java files under the ${src}
-directory, and stores the .class files in the
-${build} directory. This will fork off the javac
-compiler using the executable named java$javac.exe. Note
-that the $ sign needs to be escaped by a second one.
<javac srcdir="${src}"
- destdir="${build}"
- includes="mypackage/p1/**,mypackage/p2/**"
- excludes="mypackage/p1/testpackage/**"
- classpath="xyz.jar"
- debug="on"
- />
-compiles .java files under the ${src}
-directory, and stores the
-.class files in the ${build} directory.
-The classpath used contains xyz.jar, and debug information is on.
-Only files under mypackage/p1 and mypackage/p2 are
-used. Files in the mypackage/p1/testpackage directory are excluded
-from compilation.
<javac srcdir="${src}:${src2}"
- destdir="${build}"
- includes="mypackage/p1/**,mypackage/p2/**"
- excludes="mypackage/p1/testpackage/**"
- classpath="xyz.jar"
- debug="on"
- />
-
-is the same as the previous example, with the addition of a second
-source path, defined by
-the property src2. This can also be represented using nested
-<src> elements as follows:
<javac destdir="${build}"
- classpath="xyz.jar"
- debug="on">
- <src path="${src}"/>
- <src path="${src2}"/>
- <include name="mypackage/p1/**"/>
- <include name="mypackage/p2/**"/>
- <exclude name="mypackage/p1/testpackage/**"/>
- </javac>
-
-Note: If you are using Ant on Windows and a new DOS window pops up -for every use of an external compiler, this may be a problem of the JDK you are using. -This problem may occur with all JDKs < 1.2.
- -Note: If you wish to compile only source-files located in some packages below a -common root you should not include these packages in the srcdir-attribute. Use include/exclude-attributes -or elements to filter for these packages. If you include part of your package-structure inside the srcdir-attribute -(or nested src-elements) Ant will start to recompile your sources every time you call it.
- -Jikes supports some extra options, which can be set be defining -properties prior to invoking the task. The ant developers are aware that -this is ugly and inflexible -expect a better solution in the future. All -the options are boolean, and must be set to "true" or "yes" to be -interpreted as anything other than false; by default -build.compiler.warnings is "true" while all others are "false"
- -| - build.compiler.emacs - | -- Enable emacs compatible error messages - | -
|
- build.compiler.warnings - This property has been deprecated, use the nowarn attribute - instead - |
- - don't disable warning messages - | -
| - build.compiler.pedantic - | -- enable pedantic warnings - | -
| - build.compiler.fulldepend - | -
- enable full dependency checking, - "+F" in the jikes manual. - |
-
Generates code documentation using the javadoc tool.
- -The source directory will be recursively scanned for Java source files to process -but only those matching the inclusion rules, and not matching the exclusions rules -will be passed to the javadoc tool. This -allows wildcards to be used to choose between package names, reducing verbosity -and management costs over time. This task, however, has no notion of -"changed" files, unlike the javac task. This means -all packages will be processed each time this task is run. In general, however, -this task is used much less frequently.
- -This task works seamlessly between different javadoc versions (1.1 and 1.2), -with the obvious restriction that the 1.2 attributes will be ignored if run in a -1.1 VM.
- -NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the -same VM as ant without breaking functionality. For this reason, this task -always forks the VM. This overhead is not significant since javadoc is normally a heavy -application and will be called infrequently.
- -NOTE: the packagelist attribute allows you to specify the list of packages to -document outside of the Ant file. It's a much better practice to include everything -inside the build.xml file. This option was added in order to make it easier to -migrate from regular makefiles, where you would use this option of javadoc. -The packages listed in packagelist are not checked, so the task performs even -if some packages are missing or broken. Use this option if you wish to convert from -an existing makefile. Once things are running you should then switch to the regular -notation.
- -DEPRECATION: the javadoc2 task simply points to the javadoc task and it's -there for back compatibility reasons. Since this task will be removed in future -versions, you are strongly encouraged to use javadoc -instead.
-<javadoc packagenames="com.dummy.test.*" - sourcepath="src" - excludepackagenames="com.dummy.test.doc-files.*" - defaultexcludes="yes" - destdir="docs/api" - author="true" - version="true" - use="true" - windowtitle="Test API"> - <doctitle><![CDATA[<h1>Test</h1>]]></doctitle> - <bottom><![CDATA[<i>Copyright © 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom> - <tag name="todo" scope="all" description="To do:" /> - <group title="Group 1 Packages" packages="com.dummy.test.a*"/> - <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/> - <link offline="true" href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/> - <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/> - </javadoc>-
Sets a property (by name and value), or set of properties (from file or resource) in the project.
- -Properties are case sensitive.
- -Properties are immutable: whoever sets a property first freezes it for the rest of the build; they are most definately not variable.
- -There are five ways to set properties: -
-
-
- By supplying both the name and value attribute. -
- By supplying both the name and refid attribute. -
- By setting the file attribute with the filename of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties. -
- By setting the resource attribute with the resource name of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties. -
- By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable. -
Although combinations of these ways are possible, only one should be used at a time. Problems might occur with the order in which properties are set, for instance.
- -The value part of the properties being set, might contain references to other properties. These references are resolved at the time these properties are set. This also holds for properties loaded from a property file.
- -A list of predefined properties can be found here.
- -sets the property foo.dist to the value "dist".
reads a set of properties from a file called "foo.properties".
-reads a set of properties from a resource called "foo.properties".
-Note that you can reference a global properties file for all of your Ant -builds using the following:
-since the "user.home" property is defined by the Java virtual machine -to be your home directory. Where the "user.home" property resolves to in -the file system depends on the operating system version and the JVM implementation. -On Unix based systems, this will map to the user's home directory. On modern Windows -variants, this will most likely resolve to the user's directory in the "Documents -and Settings" folder. Older windows variants such as Windows 98/ME are less -predictable, as are other operating system/JVM combinations.
- -reads the system environment variables and stores them in properties, prefixed with "env". -Note that this only works on select operating systems. -Two of the values are shown being echoed. -
- -
- Calls a given target for all defined sub-builds.
- This is an extension
- of ant for bulk project execution.
-
- This task must no be used outside of a
- target if it invokes the same build file it is
- part of.
-
- subant can be used with directory sets to execute a build from different directories. - 2 different options are offered : -
--
-
-
- to run the same build file
/somepath/otherpath/mybuild.xml- with different base directories, use the genericantfile attribute -
- - if you want to run
directory1/mybuild.xml,directory2/mybuild.xml,...., - use the antfile attribute. The subant task does not set the base directory for you in this case, because you can specify it in each build file. -
-
- <project name="subant" default="subant1"> - <property name="build.dir" value="subant.build"/> - <target name="subant1"> - <subant target=""> - <property name="build.dir" value="subant1.build"/> - <property name="not.overloaded" value="not.overloaded"/> - <fileset dir="." includes="*/build.xml"/> - </subant> - </target> - </project> --
- this snippet build file will run ant in each subdirectory of the project directory, - where a file called build.xml can be found. - The property build.dir will have the value subant1.build in the ant projects called by subant. -
-- <subant target=""> - <propertyset> - <propertyref prefix="toplevel"/> - <mapper type="glob" from="foo*" to="bar*"/> - </propertyset> - <fileset dir="." includes="*/build.xml"/> - </subant> --
- this snippet build file will run ant in each subdirectory of the project directory, - where a file called build.xml can be found. - All properties whose name starts with "foo" are passed, their names are changed to start with "bar" instead -
-- <subant target="compile" genericantfile="/opt/project/build1.xml"> - <dirset dir="." includes="projects*"/> - </subant> --
- assuming the subdirs of the project dir are called projects1, projects2, projects3 - this snippet will execute the compile target of /opt/project/build1.xml, - setting the basedir to projects1, projects2, projects3 -
-Now a little more complex - but useful - scenario. Assume that we have - a directory structure like this:
-- root - | common.xml - | build.xml - | - +-- modules - +-- modA - | +-- src - +-- modB - +-- src - - common.xml:- -
- <project> - <property name="src.dir" value="src"/> - <property name="build.dir" value="build"/> - <property name="classes.dir" value="${build.dir}/classes"/> - - <target name="compile"> - <mkdir dir="${classes.dir}"/> - <javac srcdir="${src.dir}" destdir="${classes.dir}"/> - </target> - - <!-- more targets --> - </project> - - build.xml:
- <project> - - <macrodef name="iterate"> - <attribute name="target"/> - <sequential> - <subant target="@{target}"> - <fileset dir="modules" includes="*/build.xml"/> - </subant> - </sequential> - </macrodef> - - - <target name="compile"> - <iterate target="compile"/> - </target> - - <!-- more targets --> - </project> - - modules/modA/build.xml:
- <project name="modA"> - <import file="../../common.xml"/> - </project> -
This results in very small buildfiles in the modules, maintainable - buildfile (common.xml) and a clear project structure. Additionally - the root buildfile is capable to run the whole build over all - modules. -
-Creates a tar archive.
- -The basedir attribute is the reference directory from where to tar.
- -This task is a directory based task -and, as such, forms an implicit Fileset. This -defines which files, relative to the basedir, will be included in the -archive. The tar task supports all the attributes of Fileset to refine the -set of files to be included in the implicit fileset.
- -In addition to the implicit fileset, the tar task supports nested filesets. These -filesets are extended to allow control over the access mode, username and groupname -to be applied to the tar entries. This is useful, for example, when preparing archives for -Unix systems where some files need to have execute permission.
- -Early versions of tar did not support path lengths greater than 100
-characters. Modern versions of tar do so, but in incompatible ways.
-The behaviour of the tar task when it encounters such paths is
-controlled by the longfile attribute.
-If the longfile attribute is set to fail, any long paths will
-cause the tar task to fail. If the longfile attribute is set to
-truncate, any long paths will be truncated to the 100 character
-maximum length prior to adding to the archive. If the value of the longfile
-attribute is set to omit then files containing long paths will be
-omitted from the archive. Either option ensures that the archive can be
-untarred by any compliant version of tar. If the loss of path or file
-information is not acceptable, and it rarely is, longfile may be set to the
-value gnu. The tar task will then produce a GNU tar file which
-can have arbitrary length paths. Note however, that the resulting archive will
-only be able to be untarred with GNU tar. The default for the longfile
-attribute is warn which behaves just like the gnu option except
-that it produces a warning for each file path encountered that does not match
-the limit.
Note that this task does not perform compression. You might want to use the -GZip task to prepare a .tar.gz package.
- <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual"/>
- <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/>
-tars all files in the htdocs/manual directory into a file called manual.tar
-in the ${dist} directory, then applies the gzip task to compress
-it.
<tar destfile="${dist}/manual.tar"
- basedir="htdocs/manual"
- excludes="mydocs/**, **/todo.html"
- />
-tars all files in the htdocs/manual directory into a file called manual.tar
-in the ${dist} directory. Files in the directory mydocs,
-or files with the name todo.html are excluded.
-<tar destfile="${basedir}/docs.tar">
- <tarfileset dir="${dir.src}/docs"
- fullpath="/usr/doc/ant/README"
- preserveLeadingSlashes="true">
- <include name="readme.txt"/>
- </tarfileset>
- <tarfileset dir="${dir.src}/docs"
- prefix="/usr/doc/ant"
- preserveLeadingSlashes="true">
- <include name="*.html"/>
- </tarfileset>
-</tar>
-
-
- Writes the file docs/readme.txt as
- /usr/doc/ant/README into the archive. All
- *.html files in the docs directory are
- prefixed by /usr/doc/ant, so for example
- docs/index.html is written as
- /usr/doc/ant/index.html to the archive.
-
<tar longfile="gnu"
- destfile="${dist.base}/${dist.name}-src.tar" >
- <tarfileset dir="${dist.name}/.." mode="755" username="ant" group="ant">
- <include name="${dist.name}/bootstrap.sh"/>
- <include name="${dist.name}/build.sh"/>
- </tarfileset>
- <tarfileset dir="${dist.name}/.." username="ant" group="ant">
- <include name="${dist.name}/**"/>
- <exclude name="${dist.name}/bootstrap.sh"/>
- <exclude name="${dist.name}/build.sh"/>
- </tarfileset>
-</tar>
-
-This example shows building a tar which uses the GNU extensions for long paths and -where some files need to be marked as executable (mode 755) -and the rest are use the default mode (read-write by owner). The first -fileset selects just the executable files. The second fileset must exclude -the executable files and include all others.
- -Note: The tar task does not ensure that a file is only selected -by one fileset. If the same file is selected by more than one fileset, it will be included in the -tar file twice, with the same path.
- -Note: The patterns in the include and exclude
-elements are considered to be relative to the corresponding dir
-attribute as with all other filesets. In the example above,
-${dist.name} is not an absolute path, but a simple name
-of a directory, so ${dist.name} is a valid path relative
-to ${dist.name}/...