Date: 2004-03-12T19:12:37
Editor: 203.121.47.163 <>
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
------------------------------------------------------------------------------
@@ -39,20 +39,23 @@
==== 6. Use ANT_OPTS to control Ant?s virtual machine settings. ====
Some tasks may require more memory, which you can set in the ANT_OPTS
environment variable, using the appropriate mechanism for your platform:
-{{{ set ANT_OPTS=-Xmx500M }}}
-{{{ set ANT_OPTS=-Xmx500M ; export ANT_OPTS }}}
+{{{
+ set ANT_OPTS=-Xmx500M
+ set ANT_OPTS=-Xmx500M ; export ANT_OPTS }}}
==== 7. Use ANT_ARGS to set fixed command-line switches. ====
You may always want to use the -emacs and the NoBannerLogger:
-{{{ set ANT_ARGS=-emacs -logger org.apache.tools.ant.NoBannerLogger }}}
-{{{ export ANT_ARGS=-emacs -logger org.apache.tools.ant.NoBannerLogger }}}
+{{{
+ set ANT_ARGS=-emacs -logger org.apache.tools.ant.NoBannerLogger
+ export ANT_ARGS=-emacs -logger org.apache.tools.ant.NoBannerLogger }}}
Other settings that may be useful in ANT_ARGS are:
-{{{ -Dbuild.compiler=jikes }}}
-{{{ -listener org.apache.tools.ant.tools.listener.Log4jListener }}}
-{{{ -propertyfile my.properties. }}}
+{{{
+ -Dbuild.compiler=jikes
+ -listener org.apache.tools.ant.tools.listener.Log4jListener
+ -propertyfile my.properties. }}}
----
@@ -70,12 +73,13 @@
==== 9. Use consistent indentation. ====
Keep <project> at the very left edge, along with the <?xml ?> tag. Two or four
spaces is typical, no hard tabs. Keep closing elements aligned with opening
elements, as in <target> here:
-{{{ <?xml version="1.0"?> }}}
-{{{ <project> }}}
-{{{ ..<target name="init"> }}}
-{{{ ....<mkdir dir="${build.dir}"/> }}}
-{{{ ..</target> }}}
-{{{ </project> }}}
+{{{
+ <?xml version="1.0"?>
+ <project>
+ ..<target name="init">
+ ....<mkdir dir="${build.dir}"/>
+ ..</target>
+ </project> }}}
==== 10. One-line elements are acceptable. ====
This typically only applies to elements that combine their start and finish
tags into one.
@@ -91,11 +95,12 @@
Place the first attribute of an XML element on the same line as the start
element tag, and place subsequent attributes on new lines indented to the same
level as the first attribute.
-{{{ <javac destdir="${build.classes.dir}" }}}
-{{{ debug="${build.debug}" }}}
-{{{ includeAntRuntime="yes" }}}
-{{{ srcdir="${src.dir}" }}}
-{{{ /> }}}
+{{{
+ <javac destdir="${build.classes.dir}"
+ debug="${build.debug}"
+ includeAntRuntime="yes"
+ srcdir="${src.dir}"
+ /> }}}
If an attribute value still pushes past the established line length limit,
consider splitting the value into multiple properties and concatenating their
values.
Close self-contained elements on a new line, as shown here, with the />
characters aligned vertically with the opening < - this helps visually notice
the entire block as a unit.
@@ -107,19 +112,20 @@
==== 13. Define tasks, datatypes, and properties before targets. ====
Some tasks are allowed outside targets: <taskdef>, <typedef>, and <property>.
All datatype declarations are also allowed outside of targets. When possible,
place task, datatype, and property definitions prior to the first target as
child elements of <project>.
-{{{ <?xml version="1.0" ?> }}}
-{{{ <project name="library" default="main"> }}}
+{{{
+ <?xml version="1.0" ?>
+ <project name="library" default="main">
-{{{ <property name="tasks.jar" location="dist/tasks.jar"/> }}}
-{{{ <taskdef resource="taskdef.properties" classpath="${tasks.jar}"/> }}}
-{{{ }}}
-{{{ <path id="the.path" includes="${tasks.jar}"/> }}}
-
-{{{ <target name="usetasks"> }}}
-{{{ <sometask refid="the.path"/> }}}
-{{{ </target> }}}
+ <property name="tasks.jar" location="dist/tasks.jar"/>
+ <taskdef resource="taskdef.properties" classpath="${tasks.jar}"/>
-{{{ </project> }}}
+ <path id="the.path" includes="${tasks.jar}"/>
+
+ <target name="usetasks">
+ <sometask refid="the.path"/>
+ </target>
+
+ </project> }}}
Some exceptions apply, such as compiling and using a custom task in the same
build - this requires the <taskdef> to be inside a target dependent upon
compilation.
@@ -128,30 +134,33 @@
==== 14. Order attributes logically and consistently. ====
Define targets with name first so that it is easy to spot visually.
-{{{ <target name="deploy" depends="package" if="deploy.server"> }}}
-{{{ <!-- ... --> }}}
-{{{ </target> }}}
+{{{
+ <target name="deploy" depends="package" if="deploy.server">
+ <!-- ... -->
+ </target> }}}
For commonly used tasks, such as <javac>, establish a preferred ordering of
attributes and be consistent across projects:
-{{{ <javac srcdir="${src.dir}" }}}
-{{{ destdir="${build.classes.dir}" }}}
-{{{ classpathref="compile.classpath" }}}
-{{{ debug="${build.debug}" }}}
-{{{ includeAntRuntime="yes" }}}
-{{{ /> }}}
-{{{ }}}
+{{{
+ <javac srcdir="${src.dir}"
+ destdir="${build.classes.dir}"
+ classpathref="compile.classpath"
+ debug="${build.debug}"
+ includeAntRuntime="yes"
+ /> }}}
+
==== 15. Use XML entity references to include common fragments. ====
-{{{ <?xml version="1.0"?> }}}
-{{{ <!DOCTYPE project [ }}}
-{{{ <!ENTITY properties SYSTEM "file:../properties.xml"> }}}
-{{{ ]> }}}
-{{{ <project name="Sub-project" default="main"> }}}
+{{{
+ <?xml version="1.0"?>
+ <!DOCTYPE project [
+ <!ENTITY properties SYSTEM "file:../properties.xml">
+ ]>
+ <project name="Sub-project" default="main">
-{{{ &properties; }}}
+ &properties;
-{{{ </project> }}}
+ </project> }}}
15.1 Ant 1.6 adds an <import> statement that lets you import XML fragments
into the build file, supporting ant properties in the declaration of the file
to import. Use this in preference to to the entity reference trick, when you
can. Be aware that the rules as to *where* the import is inserted into the file
are different between the two mechanisms -consult the <import> documentation
for up to date details.
@@ -172,18 +181,19 @@
The following targets are common to many builds. Always avoid changing the
behavior of a well-known target name. You do not need to implement all of these
in a single project.
-{{{ '''all''' Build and test everything; create a
distribution, optionally install. }}}
-{{{ '''clean''' Delete all generated files and directories. }}}
-{{{ '''deploy''' Deploy the code, usually to a remote server. }}}
-{{{ '''dist''' Produce the distributables. }}}
-{{{ '''distclean''' Clean up the distribution files only. }}}
-{{{ '''docs''' Generate all documentation. }}}
-{{{ '''init''' Initialize the build: create directories, call
<tstamp> and other common actions. }}}
-{{{ '''install''' Perform a local installation. }}}
-{{{ '''javadocs''' Generate the Javadoc pages. }}}
-{{{ '''printerdocs''' Generate printable documents. }}}
-{{{ '''test''' Run the unit tests. }}}
-{{{ '''uninstall''' Remove a local installation. }}}
+{{{
+ '''all''' Build and test everything; create a distribution,
optionally install.
+ '''clean''' Delete all generated files and directories.
+ '''deploy''' Deploy the code, usually to a remote server.
+ '''dist''' Produce the distributables.
+ '''distclean''' Clean up the distribution files only.
+ '''docs''' Generate all documentation.
+ '''init''' Initialize the build: create directories, call
<tstamp> and other common actions.
+ '''install''' Perform a local installation.
+ '''javadocs''' Generate the Javadoc pages.
+ '''printerdocs''' Generate printable documents.
+ '''test''' Run the unit tests.
+ '''uninstall''' Remove a local installation. }}}
Never override a well-known target name with a different behavior, as then the
build file will behave unexpectedly to new users. For example, the docs task
should not install the system as a side effect, as that is not what is
expected.
@@ -193,15 +203,16 @@
==== 19. Use consistent default target name across projects. ====
A standard default project target name allows for easy invocation from the
command-line.
-{{{ <project name="elements" default="default"> }}}
+{{{
+ <project name="elements" default="default">
-{{{ <target name="clean"> }}}
-{{{ <!-- ... --> }}}
-{{{ </target> }}}
+ <target name="clean">
+ <!-- ... -->
+ </target>
-{{{ <target name="default" depends="..."/> }}}
+ <target name="default" depends="..."/>
-{{{ </project> }}}
+ </project> }}}
The targets main and default make good standard default target names, although
this is an area of personal preference. Whatever you choose, be consistent
across all projects. To invoke a default clean build, run ant clean default .
@@ -231,17 +242,18 @@
Using indirection keeps a build file decoupled from the location and version
of third-party libraries.
''build.xml''
-{{{ <property name="lib.dir" location="../somewhere/libs"/> }}}
-{{{ <property file="${lib.dir}/lib.properties"/> }}}
-
-{{{ ... }}}
-{{{ <classpath id="compile.classpath" }}}
-{{{ path="${oro.jar}:${xalan.jar}" }}}
-{{{ /> }}}
+{{{
+ <property name="lib.dir" location="../somewhere/libs"/>
+ <property file="${lib.dir}/lib.properties"/>
+
+ ...
+ <classpath id="compile.classpath"
+ path="${oro.jar}:${xalan.jar}"
+ /> }}}
''lib.properties''
-{{{ xalan.jar=${lib.dir}/java/jakarta-xalan2/xalan.jar }}}
-{{{ oro.jar=${lib.dir}/java/jakarta-oro/jakarta-oro-2.0.6.jar }}}
+{{{ xalan.jar=${lib.dir}/java/jakarta-xalan2/xalan.jar
+ oro.jar=${lib.dir}/java/jakarta-oro/jakarta-oro-2.0.6.jar }}}
(submitted by Stephane Bailliez)
@@ -265,16 +277,17 @@
The following table lists directory names commonly found in Ant projects. The
build and dist directories should contain nothing in them that Ant cannot
build, so clean can clean up just by deleting them.
-{{{ '''build''' Temporarily used as a staging area for classes
and more. }}}
-{{{ '''dist''' Distribution directory. }}}
-{{{ '''docs''' Documentation files stored in their presentation
format. }}}
-{{{ '''etc''' Sample files. }}}
-{{{ '''lib''' Project dependencies, typically third party .jar
files. }}}
-{{{ '''src''' Root directory of Java source code, package
directory structure below. }}}
-{{{ '''src/xdocs''' Documentation in XML format, to be transformed
into presentation format during the build process. }}}
-{{{ '''src/META-INF''' Metadata for the JAR file. }}}
-{{{ '''web''' Root directory of web content (.html, .jpg,
.JSP). }}}
-{{{ '''web/WEB-INF''' Web deployment information, such as web.xml. }}}
+{{{
+ '''build''' Temporarily used as a staging area for classes and
more.
+ '''dist''' Distribution directory.
+ '''docs''' Documentation files stored in their presentation
format.
+ '''etc''' Sample files.
+ '''lib''' Project dependencies, typically third party .jar
files.
+ '''src''' Root directory of Java source code, package
directory structure below.
+ '''src/xdocs''' Documentation in XML format, to be transformed into
presentation format during the build process.
+ '''src/META-INF''' Metadata for the JAR file.
+ '''web''' Root directory of web content (.html, .jpg, .JSP).
+ '''web/WEB-INF''' Web deployment information, such as web.xml. }}}
The actual naming and placement of directories somewhat controversial, as many
different projects have their own historical preference. All good layouts tend
to have these features:
* Source files are cleanly split from generated files; Java class files are
never generated into the same directory as the source. This makes it much
easier to clean a project of all generated content, and reduces the risk of any
accidental destruction of source files.
@@ -289,60 +302,65 @@
==== 30. Define a project <description>. ====
This is visible in the build file, but is also displayed when the ?projecthelp
switch is used.
-{{{ <project name="elements" default="default"> }}}
-{{{ <description>The Elements of Ant Style project</description> }}}
-
-{{{ <target name="default" }}}
-{{{ description="Public target" }}}
-{{{ /> }}}
+{{{
+ <project name="elements" default="default">
+ <description>The Elements of Ant Style project</description>
+
+ <target name="default"
+ description="Public target"
+ />
-{{{ </project> }}}
+ </project> }}}
Running ant -projecthelp shows the description
-{{{ Buildfile: build.xml }}}
-{{{ The Elements of Ant Style project }}}
-{{{ Main targets: }}}
+{{{
+ Buildfile: build.xml
+ The Elements of Ant Style project
+ Main targets:
-{{{ default Public target }}}
+ default Public target
-{{{ Default target: default }}}
+ Default target: default }}}
==== 31. Use comments liberally. ====
Be succinct and do not repeat what is already obvious from the build file
elements. There is no need to say <!-- compile the code --> followed by <javac>.
Here is an example of a block comment to separate sections visibly.
-{{{ <!-- ===================================================== --> }}}
-{{{ <!-- Datatype declarations --> }}}
-{{{ <!-- ===================================================== --> }}}
-{{{ <path id="compile.classpath"> }}}
-{{{ <pathelement location="${lucene.jar}"/> }}}
-{{{ <pathelement location="${jtidy.jar}"/> }}}
-{{{ </path> }}}
+{{{
+ <!-- ===================================================== -->
+ <!-- Datatype declarations -->
+ <!-- ===================================================== -->
+ <path id="compile.classpath">
+ <pathelement location="${lucene.jar}"/>
+ <pathelement location="${jtidy.jar}"/>
+ </path> }}}
''One general comment (no pun intended) regarding XML comments. The above
"comment" is actually 3 comments from XML's perspective. The following
convention ensures that if you do something like use XSLT to generate reports
from your build.xml files, then the XSLT won't have to do the extra work of
taking the individual comments and combining them into one. Also, tools that
display XML will show a single comment, not three distinct comments. It's not
so bad in this example, but when the comment is 20 lines long, 20 individual
1-line comments can become hard to follow.''
-{{{ <!-- ===================================================== }}}
-{{{ Datatype declarations }}}
-{{{ ===================================================== --> }}}
-{{{ <path id="compile.classpath"> }}}
-{{{ <pathelement location="${lucene.jar}"/> }}}
-{{{ <pathelement location="${jtidy.jar}"/> }}}
-{{{ </path> }}}
+{{{
+ <!-- =====================================================
+ Datatype declarations
+ ===================================================== -->
+ <path id="compile.classpath">
+ <pathelement location="${lucene.jar}"/>
+ <pathelement location="${jtidy.jar}"/>
+ </path> }}}
''
==== 32. Define a usage target. ====
If your build file is used mostly by new users, having the default target
display usage information will help them get started.
-{{{ <project name="MyProject" default="usage" basedir=".."> }}}
-{{{ <target name="usage"> }}}
-{{{ <echo message=" Execute 'ant -projecthelp' for build file help."/>
}}}
-{{{ <echo message=" Execute 'ant -help' for Ant help."/> }}}
-{{{ </target> }}}
-{{{ ... }}}
-{{{ </project> }}}
+{{{
+ <project name="MyProject" default="usage" basedir="..">
+ <target name="usage">
+ <echo message=" Execute 'ant -projecthelp' for build file help."/>
+ <echo message=" Execute 'ant -help' for Ant help."/>
+ </target>
+ ...
+ </project> }}}
(submitted by Bobby Woolf)
You may, alternatively, want your default target to perform the primary build
of the project but still have a usage target that can be invoked if needed.
@@ -358,11 +376,12 @@
==== 35. Give primary targets a description. ====
Targets with a description appear as "Main targets" in the -projecthelp
output. The description should be succinct and provide information beyond what
the actual target name implies.
-{{{ <target name="gen-ejb" }}}
-{{{ description="Generate EJB code from @tags" }}}
-{{{ depends="init"> }}}
-{{{ <!-- ... --> }}}
-{{{ </target> }}}
+{{{
+ <target name="gen-ejb"
+ description="Generate EJB code from @tags"
+ depends="init">
+ <!-- ... -->
+ </target> }}}
Higher-level build process documentation or diagrams can be generated from a
build file using XSL transformations or other techniques (submitted by Greg
'Cosmo' Haun). This is a rationale for keeping descriptions short. Use XML
comments for more detailed information if necessary.
@@ -387,9 +406,10 @@
Metadata resources are often kept alongside source code, or in parallel
directory trees to allow for customer customization or test data, for example.
These files are typically property files or XML files, such as resource bundles
used for localization.
Tests may assume these files are available on the classpath. Copying these
non-source files to the directory where source files are compiled to allows
them to be picked up automatically during packaging and testing.
-{{{ <copy todir="${test.classes.dir}"> }}}
-{{{ <fileset dir="${test.src.dir}" includes="**/*.properties"/> }}}
-{{{ </copy> }}}
+{{{
+ <copy todir="${test.classes.dir}">
+ <fileset dir="${test.src.dir}" includes="**/*.properties"/>
+ </copy> }}}
=== Targets ===
@@ -409,20 +429,21 @@
==== 41. Handle creation and deletion of property referenced directories
individually. ====
Do not assume that hierarchically named properties refer to hierarchically
structured directories.
-{{{ <project name="DirectoryExample" default="init"> }}}
-{{{ <property name="build.dir" location="build"/> }}}
-{{{ <property name="build.classes.dir" location="${build.dir}/classes"/>
}}}
-
-{{{ <target name="init"> }}}
-{{{ <mkdir dir="${build.dir}"/> }}}
-{{{ <mkdir dir="${build.classes.dir}"/> }}}
-{{{ </target> }}}
-
-{{{ <target name="clean"> }}}
-{{{ <delete dir="${build.dir}"/> }}}
-{{{ <delete dir="${build.classes.dir}"/> }}}
-{{{ </target> }}}
-{{{ </project> }}}
+{{{
+ <project name="DirectoryExample" default="init">
+ <property name="build.dir" location="build"/>
+ <property name="build.classes.dir" location="${build.dir}/classes"/>
+
+ <target name="init">
+ <mkdir dir="${build.dir}"/>
+ <mkdir dir="${build.classes.dir}"/>
+ </target>
+
+ <target name="clean">
+ <delete dir="${build.dir}"/>
+ <delete dir="${build.classes.dir}"/>
+ </target>
+ </project> }}}
The <mkdir> task will make multiple levels of directories if they do not
exist, so if only <mkdir dir="${build.classes.dir}"/> was used in the init
target, both the build and build/classes directories would be created. However,
because properties are designed to be overridden you cannot assume that
build.classes.dir is physically under build.dir. A master build file may wish
to redirect specific output.
@@ -430,18 +451,19 @@
Properties are immutable. This fact alone can be the source of frustration for
those seeking to implement variables, or the source of great flexibility when
used properly. A property sticks with its first value set, and all future
attempts to change it are ignored.
Load properties in the desired order of precedence. The needs of the project,
development team, and organization dictate the specific order needed. Loading
user-specific properties is a convention all projects should follow. The
following code is an example of typical property ordering:
-{{{ <!-- Load environment variables --> }}}
-{{{ <property environment="env"/> }}}
-
-{{{ <property name="user.properties.file" }}}
-{{{ location="${user.home}/.build.properties" }}}
-{{{ /> }}}
+{{{
+ <!-- Load environment variables -->
+ <property environment="env"/>
+
+ <property name="user.properties.file"
+ location="${user.home}/.build.properties"
+ />
-{{{ <!-- Load the project specific settings --> }}}
-{{{ <property file="build.properties"/> }}}
+ <!-- Load the project specific settings -->
+ <property file="build.properties"/>
-{{{ <!-- Load user specific settings --> }}}
-{{{ <property file="${user.properties.file}"/> }}}
+ <!-- Load user specific settings -->
+ <property file="${user.properties.file}"/> }}}
This fragment loads all environment variables as Ant properties first. The
user-specific properties file is mapped to an Ant property so that its location
can itself be overridden, but it is not loaded until after the project-specific
properties are loaded. This allows a project to have more say in its settings
than a users preference, if it is needed.
@@ -452,13 +474,15 @@
Don't do this:
-{{{ <property name="build.dir" location="build"/> }}}
-{{{ <property name="build.classes" location="build/classes"/> }}}
+{{{
+ <property name="build.dir" location="build"/>
+ <property name="build.classes" location="build/classes"/> }}}
Do this instead:
-{{{ <property name="build.dir" location="build"/> }}}
-{{{ <property name="build.classes" location="${build.dir}/classes"/> }}}
+{{{
+ <property name="build.dir" location="build"/>
+ <property name="build.classes" location="${build.dir}/classes"/> }}}
The difference becomes apparent when a user or master build wants to override
build.dir. In the first example, only build.dir is relocated to the overridden
directory, but build.classes will remain under the base directory. In the
second example, overriding build.dir has the desired effect of moving all child
directories too.
@@ -467,8 +491,9 @@
Defaulting the build.number property to zero if it is not set in a properties
file takes advantage of property immutability.
-{{{ <property file="build.properties"/> }}}
-{{{ <property name="build.number" value="0"/> }}}
+{{{
+ <property file="build.properties"/>
+ <property name="build.number" value="0"/> }}}
If build.number is loaded from build.properties, the second <property> task is
essentially ignored.
@@ -483,8 +508,9 @@
To load two server configuration files with unique prefixes, use prefix.
-{{{ <property file="server1.properties" prefix="server1"/> }}}
-{{{ <property file="server2.properties" prefix="server2"/> }}}
+{{{
+ <property file="server1.properties" prefix="server1"/>
+ <property file="server2.properties" prefix="server2"/> }}}
Both files may have a server.name property, but they will be accessible as
server1.server.name and server2.server.name Ant properties.
@@ -494,17 +520,18 @@
This eases build file maintenance. Adding a new dependency to the compile
classpath, in this example, automatically includes it in the test classpath.
-{{{ <path id="compile.classpath"> }}}
-{{{ <pathelement location="${lucene.jar}"/> }}}
-{{{ <pathelement location="${jtidy.jar}"/> }}}
-{{{ </path> }}}
-
-{{{ <path id="test.classpath"> }}}
-{{{ <path refid="compile.classpath"/> }}}
-{{{ <pathelement location="${junit.jar}"/> }}}
-{{{ <pathelement location="${build.classes.dir}"/> }}}
-{{{ <pathelement location="${test.classes.dir}"/> }}}
-{{{ </path> }}}
+{{{
+ <path id="compile.classpath">
+ <pathelement location="${lucene.jar}"/>
+ <pathelement location="${jtidy.jar}"/>
+ </path>
+
+ <path id="test.classpath">
+ <path refid="compile.classpath"/>
+ <pathelement location="${junit.jar}"/>
+ <pathelement location="${build.classes.dir}"/>
+ <pathelement location="${test.classes.dir}"/>
+ </path> }}}
=== Classpath ===
@@ -513,18 +540,18 @@
==== 47. Use explicit classpaths wherever possible. ====
Although some libraries must be in ANT_HOME/lib, keep the ones that are not
needed there in a separate location, and refer to them with Ant properties to
allow for overriding. Avoid, if possible, using filesets to pull *.jar into a
path declaration, as this makes the build file break if conflicting JAR files
are added later.
-{{{ <path id="task.classpath"> }}}
-{{{ <pathelement location="${build.dir}"/> }}}
-{{{ <pathelement location="${antbook-common.jar}"/> }}}
-{{{ <pathelement location="${lucene.jar}"/> }}}
-{{{ </path> }}}
-
-{{{ <java classname="org.example.antbook.tasks.Searcher" }}}
-{{{ fork="true" }}}
-{{{ classpathref="task.classpath"> }}}
-{{{ <arg file="${index.dir}"/> }}}
-{{{ <arg value="${query}"/> }}}
-{{{ </java> }}}
+{{{ <path id="task.classpath">
+ <pathelement location="${build.dir}"/>
+ <pathelement location="${antbook-common.jar}"/>
+ <pathelement location="${lucene.jar}"/>
+ </path>
+
+ <java classname="org.example.antbook.tasks.Searcher"
+ fork="true"
+ classpathref="task.classpath">
+ <arg file="${index.dir}"/>
+ <arg value="${query}"/>
+ </java> }}}
==== 48. Turn off includeAntRuntime on <javac>. ====
By default, includeAntRuntime is true. There is no need for it to be in the
classpath unless you are building custom Ant tasks. Even then, it is not
necessary as you can include ${ant.home}/lib/ant.jar in the classpath manually.
@@ -534,22 +561,23 @@
This example invokes ["JavaNCSS"] on a set of source files, producing an XML
output file.
-{{{ <path id="ncss.classpath"> }}}
-{{{ <fileset dir="${ncss.lib.dir}" includes="**/*.jar" /> }}}
-{{{ </path> }}}
-
-{{{ <target name="ncss" depends="compile"> }}}
-{{{ <property name="cp" refid="ncss.classpath" /> }}}
-{{{ <apply executable="java" }}}
-{{{ parallel="true" }}}
-{{{ dir="${src.dir}" }}}
-{{{ output="${build.dir}/${ant.project.name}-ncss.xml"> }}}
-{{{ <arg line="-cp %classpath%;${cp}" /> }}}
-{{{ <arg value="javancss.Main" /> }}}
-{{{ <arg line="-package -xml" /> }}}
-{{{ <fileset dir="${src.dir}" includes="**/*.java" /> }}}
-{{{ </apply> }}}
-{{{ </target> }}}
+{{{
+ <path id="ncss.classpath">
+ <fileset dir="${ncss.lib.dir}" includes="**/*.jar" />
+ </path>
+
+ <target name="ncss" depends="compile">
+ <property name="cp" refid="ncss.classpath" />
+ <apply executable="java"
+ parallel="true"
+ dir="${src.dir}"
+ output="${build.dir}/${ant.project.name}-ncss.xml">
+ <arg line="-cp %classpath%;${cp}" />
+ <arg value="javancss.Main" />
+ <arg line="-package -xml" />
+ <fileset dir="${src.dir}" includes="**/*.java" />
+ </apply>
+ </target> }}}
(submitted by Paul Holser)
@@ -569,19 +597,20 @@
==== 53. Incorporate the single test case trick ====
The nested <test> and <batchtest> elements of <junit> allow for if/unless
conditions. This facilitates a single test case to be run when desired, or all
tests by default.
-{{{ <junit printsummary="no" }}}
-{{{ errorProperty="test.failed" }}}
-{{{ failureProperty="test.failed" }}}
-{{{ fork="${junit.fork}"> }}}
-{{{ <classpath refid="test.classpath"/> }}}
-
-{{{ <test name="${testcase}" if="testcase"/> }}}
-{{{ <batchtest todir="${test.data.dir}" unless="testcase"> }}}
-{{{ <fileset dir="${test.classes.dir}" }}}
-{{{ includes="**/*Test.class" }}}
-{{{ /> }}}
-{{{ </batchtest> }}}
-{{{ </junit> }}}
+{{{
+ <junit printsummary="no"
+ errorProperty="test.failed"
+ failureProperty="test.failed"
+ fork="${junit.fork}">
+ <classpath refid="test.classpath"/>
+
+ <test name="${testcase}" if="testcase"/>
+ <batchtest todir="${test.data.dir}" unless="testcase">
+ <fileset dir="${test.classes.dir}"
+ includes="**/*Test.class"
+ />
+ </batchtest>
+ </junit> }}}
During development, a single test case can be isolated and run from the
command-line:
@@ -590,40 +619,42 @@
==== 54. Fail builds when tests fail. ====
By default, the <junit> task does not halt a build when failures occur. If no
reporting is desired, enable haltonfailure and haltonerror. However, reporting
of test cases is often desired. To accomplish reporting of test failures and
failing the build together, borrow this example:
-{{{ <junit printsummary="no" }}}
-{{{ errorProperty="test.failed" }}}
-{{{ failureProperty="test.failed" }}}
-{{{ fork="${junit.fork}"> }}}
-{{{ <!-- ... --> }}}
-{{{ </junit> }}}
-
-{{{ <junitreport todir="${test.data.dir}"> }}}
-{{{ <fileset dir="${test.data.dir}"> }}}
-{{{ <include name="TEST-*.xml"/> }}}
-{{{ </fileset> }}}
-{{{ <report format="frames" todir="${test.reports.dir}"/> }}}
-{{{ </junitreport> }}}
-
-{{{ <fail if="test.failed"> }}}
-{{{ Unit tests failed. Check log or reports for details }}}
-{{{ </fail> }}}
+{{{
+ <junit printsummary="no"
+ errorProperty="test.failed"
+ failureProperty="test.failed"
+ fork="${junit.fork}">
+ <!-- ... -->
+ </junit>
+
+ <junitreport todir="${test.data.dir}">
+ <fileset dir="${test.data.dir}">
+ <include name="TEST-*.xml"/>
+ </fileset>
+ <report format="frames" todir="${test.reports.dir}"/>
+ </junitreport>
+
+ <fail if="test.failed">
+ Unit tests failed. Check log or reports for details
+ </fail> }}}
When tests fail, the property test.failed is set, yet processing continues.
The conditional <fail> stops the build after reports are generated.
==== 55. Code test cases that need data to adapt. ====
Place test data files alongside test cases, copy the files to the test
classpath during the build, and access them using Class.getResource. Read test
configuration information from system properties, and set them from Ant. Both
of these techniques are illustrated in this example.
-{{{ <copy todir="${test.classes.dir}"> }}}
-{{{ <fileset dir="${test.src.dir}" excludes="**/*.java"/> }}}
-{{{ </copy> }}}
-{{{ <junit printsummary="no" }}}
-{{{ errorProperty="test.failed" }}}
-{{{ failureProperty="test.failed" }}}
-{{{ fork="${junit.fork}"> }}}
-{{{ <classpath refid="test.classpath"/> }}}
-{{{ <sysproperty key="docs.dir" value="${test.classes.dir}"/> }}}
-{{{ <!-- ... --> }}}
-{{{ </junit> }}}
+{{{
+ <copy todir="${test.classes.dir}">
+ <fileset dir="${test.src.dir}" excludes="**/*.java"/>
+ </copy>
+ <junit printsummary="no"
+ errorProperty="test.failed"
+ failureProperty="test.failed"
+ fork="${junit.fork}">
+ <classpath refid="test.classpath"/>
+ <sysproperty key="docs.dir" value="${test.classes.dir}"/>
+ <!-- ... -->
+ </junit> }}}
System.getProperty is used to retrieve the value of docs.dir. Our tests can be
controlled easily and values adjusted through Ant properties.
@@ -642,17 +673,19 @@
==== 57. Log important information, at the appropriate level. ====
The <echo> task has an optional level attribute. Use it to provide information
at verbose and debug levels.
-{{{ <echo level="verbose">Seen with -verbose</echo> }}}
-{{{ <echo level="debug">Seen with ?debug</echo> }}}
+{{{
+ <echo level="verbose">Seen with -verbose</echo>
+ <echo level="debug">Seen with ?debug</echo> }}}
Adding diagnostic output at the debug level can help troubleshoot errant
property values, yet the output will not be seen during normal builds. Run ant
-debug to see such output.
==== 58. Add a debug target. ====
Adding a debug target with no dependencies with an <echoproperties> can shed
light on possible misconfiguration.
-{{{ <target name="debug"> }}}
-{{{ <echoproperties/> }}}
-{{{ </target> }}}
+{{{
+ <target name="debug">
+ <echoproperties/>
+ </target> }}}
Because properties can be defined inside targets, simply running ant debug
will not necessarily display them all. Running two targets from a
single-command line execution will, as properties retain their values across
target invocations. For example, if the init target sets properties, running
ant init debug will display the properties set by init.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
