Date: 2004-03-12T19:23:05
Editor: 203.121.47.163 <>
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
------------------------------------------------------------------------------
@@ -10,16 +10,16 @@
== General principles ==
-==== 1. Let Ant be Ant. ====
+==== Let Ant be Ant. ====
Don't try to make Ant into Make. (submitted by Rich Steele, eTrack Solutions,
Inc.)
Ant is not a scripting language. It is a mostly declarative description of
steps. The declarative nature of Ant can be a source of confusion for new
users, especially if a scripting language is expected.
-==== 2. Design for componentization. ====
+==== Design for componentization. ====
A small project becomes a large project over time; splitting up a single build
into child projects with their own builds will eventually happen. You can make
this process easier by designing the build file properly from the beginning,
being sure to:
* Use <property location> to assign locations to properties, rather than
values. Not only does this stand out, it ensures that the properties are bound
to an absolute location, even when they are passed to a different project.
* Always define output directories using Ant properties. This lets master
build files define a single output tree for all child projects.
-==== 3. Design for maintenance. ====
+==== Design for maintenance. ====
Will your build file be readable when you get back to it six months after the
project is finished? Will it execute on a clean machine? Follow these points:
* Document the build process. XML may be a file format that is both human
readable and machine readable, but it is not the most easily read format for
either party. A text file covering the build and deploy process will be
appreciated by your successors. Of critical importance is the list of which
programs and libraries are needed for the build; without it, running the build
will be a trial-and-error process.
* Use comments liberally.
@@ -30,20 +30,20 @@
Environment conventions
The items in this section assume that you are launching Ant through the
wrapper scripts, such as the provided ant.bat, ant.sh, antrun.pl, or antrun.py.
-==== 4. Run without a classpath. ====
+==== Run without a classpath. ====
There is no need to manually set your system CLASSPATH environment variable.
When running through the Ant wrapper scripts, the libraries in ANT_HOME/lib are
automatically placed into the system CLASSPATH before invoking Ant. Having a
CLASSPATH variable simply increases the risk of Jar clash.
-==== 5. Place commonly used Ant library dependencies in Ant's lib directory.
====
+==== Place commonly used Ant library dependencies in Ant's lib directory. ====
In some cases it is required that libraries be in the system classpath.
JUnit's library is one of them, when using the <junit> task.
-==== 6. Use ANT_OPTS to control Ant?s virtual machine settings. ====
+==== 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 }}}
-==== 7. Use ANT_ARGS to set fixed command-line switches. ====
+==== Use ANT_ARGS to set fixed command-line switches. ====
You may always want to use the -emacs and the NoBannerLogger:
{{{
@@ -65,13 +65,13 @@
Note: some IDE's and XML editors have an annoying habit of reformatting
build.xml automatically - use these with caution if you care about the
aesthetics of your build file.
If your build file will be manually edited and readability is desired, craft
it your way and if a tool attempt to spoil it, complain to the vendor and avoid
using it.
-==== 8. Provide the <?xml?> directive. ====
+==== Provide the <?xml?> directive. ====
Include the encoding if there are characters outside the ASCII range:
{{{
<?xml version="1.0" encoding="iso-8859-1"?> }}}
-==== 9. Use consistent indentation. ====
+==== 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:
{{{
@@ -82,7 +82,7 @@
..</target>
</project> }}}
-==== 10. One-line elements are acceptable. ====
+==== One-line elements are acceptable. ====
This typically only applies to elements that combine their start and finish
tags into one.
{{{ <echo message="hello"/> }}}
@@ -92,7 +92,7 @@
{{{
<echo>build.dir = ${build.dir}</echo> }}}
-==== 11. Break up long lines. ====
+==== Break up long lines. ====
Follow similar conventions as in your Java coding. Lines typically should not
be longer than 80 characters, although other considerations may lower this
limit. Break lines when they become longer than the limit, or readability would
be increased by breaking them. These guidelines assist in breaking long lines.
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.
@@ -107,11 +107,11 @@
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.
-==== 12. Whitespace is your friend. ====
+==== Whitespace is your friend. ====
Include blank lines between logical groupings. Examples include between:
logical sets of property definitions, targets, and groupings of tasks within a
target.
-==== 13. Define tasks, datatypes, and properties before targets. ====
+==== 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>.
{{{
@@ -131,9 +131,9 @@
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.
-13.1 Ant 1.6 lets you declare anything outside of targets. Use this only for
defining things (such as with the <condition> task, rather than putting code
with side effects there. When you invoke ant with the -projecthelp option, all
the code outside of a target may get executed.
+Ant 1.6 lets you declare anything outside of targets. Use this only for
defining things (such as with the <condition> task, rather than putting code
with side effects there. When you invoke ant with the -projecthelp option, all
the code outside of a target may get executed.
-==== 14. Order attributes logically and consistently. ====
+==== Order attributes logically and consistently. ====
Define targets with name first so that it is easy to spot visually.
{{{
@@ -151,7 +151,7 @@
includeAntRuntime="yes"
/> }}}
-==== 15. Use XML entity references to include common fragments. ====
+==== Use XML entity references to include common fragments. ====
{{{
<?xml version="1.0"?>
@@ -164,7 +164,7 @@
</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.
+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,12 +172,12 @@
=== General ===
-==== 16. Use a common naming scheme among targets, datatypes, and properties.
====
+==== Use a common naming scheme among targets, datatypes, and properties. ====
Combine meaningful names, such as install, docs, and webapp, with meaningful
types like webapp.name, webapp.classpath, and docs.patternset.
=== Targets ===
-==== 17. Use consistent target names. ====
+==== Use consistent target names. ====
Standard target names keep a build file understandable over time and by new
developers. In a project with separate subprojects, each with their own build
file, it is important to keep the names consistent between projects, not just
for the benefit of programmers but for any master build mechanism.
Well-known Ant targets provide a "walk up and use" experience.
@@ -199,10 +199,10 @@
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.
-==== 18. Separate words in target names with a hyphen. ====
+==== Separate words in target names with a hyphen. ====
For example, use install-lite instead of installLite, install_lite or install
lite.
-==== 19. Use consistent default target name across projects. ====
+==== Use consistent default target name across projects. ====
A standard default project target name allows for easy invocation from the
command-line.
{{{
@@ -220,28 +220,28 @@
=== Properties ===
-==== 20. Use standard suffixes for properties directory and library
properties. ====
+==== Use standard suffixes for properties directory and library properties.
====
Use .dir for directory paths and .jar for JAR file references.
-==== 21. Prefix compilation properties with "build.". ====
+==== Prefix compilation properties with "build.". ====
The reason is somewhat historical, as build.compiler is Ant's magic property
to control which compiler is used. In keeping with this special property,
build.debug should be used to control the debug flag of <javac>. Likewise,
other <javac> parameters that you wish to control dynamically should use the
build. prefix.
-==== 22. State the role of the property first, then the type of property. ====
+==== State the role of the property first, then the type of property. ====
For example, a property representing whether tests need to be run or not is
represented as tests.uptodate.
-==== 23. Separate words with a dot (.) character in property names. ====
+==== Separate words with a dot (.) character in property names. ====
-==== 24. Lowercase property names. ====
+==== Lowercase property names. ====
Environment variables are an exception.
-==== 25. Load environment variables with ?env.? prefix. ====
+==== Load environment variables with ?env.? prefix. ====
{{{
<property env="env"/> }}}
The case of the properties loaded will be dependent upon the environment
variables, but they are typically uppercase: env.COMPUTERNAME, for example, is
the computer name on a Windows platform.
-==== 26. Abstract name and location of third-party libraries. ====
+==== Abstract name and location of third-party libraries. ====
Using indirection keeps a build file decoupled from the location and version
of third-party libraries.
''build.xml''
@@ -265,17 +265,17 @@
=== Datatypes ===
-==== 27. Use property name formatting conventions for datatype IDs. ====
+==== Use property name formatting conventions for datatype IDs. ====
In other words, lowercase datatype id?s and separate words with the dot (.)
character.
-==== 28. Standardize datatype suffixes. ====
+==== Standardize datatype suffixes. ====
Paths which represent classpaths end with .classpath, like compile.classpath.
End patternset id?s with .patternset (or simply .pattern, but be consistent).
Filesets end with .files.
----
== Directory structure ==
-==== 29. Standardize directory structures. ====
+==== Standardize directory structures. ====
A consistent organization of all projects' directory structures makes it
easier for build file reuse, either by cut-and-paste editing, or within library
build files. It also makes it easier for experienced Ant users to work with
your project.
A good directory structure is an important aspect of managing any software
development project. In relation to Ant, a well thought out directory structure
can accomplish something simply and elegantly, rather than struggling with
tangled logic and unnecessarily complex fileset definitions.
@@ -303,7 +303,7 @@
== Documentation conventions ==
-==== 30. Define a project <description>. ====
+==== Define a project <description>. ====
This is visible in the build file, but is also displayed when the ?projecthelp
switch is used.
{{{
@@ -327,7 +327,7 @@
Default target: default }}}
-==== 31. Use comments liberally. ====
+==== 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.
@@ -354,7 +354,7 @@
-==== 32. Define a usage target. ====
+==== 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.
{{{
@@ -369,16 +369,16 @@
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.
-==== 33. Alias target names to provide intuitive entry points. ====
+==== Alias target names to provide intuitive entry points. ====
For example, you may want to have a usage target but users would also type ant
help and expect assistance. An alias is simply an empty target which depends on
a non-empty target.
{{{
<target name="help" depends="usage"/> }}}
-==== 34. Include an "all" target that builds it all. ====
+==== Include an "all" target that builds it all. ====
This may not be your default target though. This target should at least create
all artifacts including documentation and distributable, but probably would not
be responsible for installation.
-==== 35. Give primary targets a description. ====
+==== 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.
{{{
@@ -392,7 +392,7 @@
----
-==== 36. Add an XSLT stylesheet to make build.xml browsable. ====
+==== Add an XSLT stylesheet to make build.xml browsable. ====
Right after the <?xml ... ?>, you can add a stylesheet reference, e.g.
@@ -409,7 +409,7 @@
=== General ===
-==== 37. Copy resources from source path to classpath. ====
+==== Copy resources from source path to classpath. ====
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.
@@ -420,21 +420,21 @@
=== Targets ===
-==== 38. Clean up after yourself. ====
+==== Clean up after yourself. ====
Make sure that all artifacts generated during a build are removed with a clean
target. You may also want a cleandist target such that the clean target only
removes the temporary build files but leaves the final distributable, and
cleandist removes everything including the generated distributable.
=== Properties ===
-==== 39. Use properties to name anything that could need overriding by the
user or a parent project. ====
+==== Use properties to name anything that could need overriding by the user or
a parent project. ====
Every output directory deserves a unique property name, suffixed by .dir.
Other items that make good candidates for properties are: configuration files,
template files used for code generation, distributable file names, application
names, user names, and passwords.
-==== 40. Use location for directory and file references. ====
+==== Use location for directory and file references. ====
This results in the full absolute path being resolved and used for the
property value, rather than just the string (likely relative path) value.
{{{
<property name="build.dir" location="build "/> }}}
-==== 41. Handle creation and deletion of property referenced directories
individually. ====
+==== Handle creation and deletion of property referenced directories
individually. ====
Do not assume that hierarchically named properties refer to hierarchically
structured directories.
{{{
@@ -455,7 +455,7 @@
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.
-==== 42. Understand and utilize property rules. ====
+==== Understand and utilize property rules. ====
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:
@@ -478,7 +478,7 @@
''I find it more useful to 'override' the project properties with user
specific properties. To do this, the order of the property file loads need to
be switched so that the user properties are loaded first (Bret Hansen)''
-==== 43. Base hierarchically named directory properties from parent directory
property. ====
+==== Base hierarchically named directory properties from parent directory
property. ====
Don't do this:
@@ -494,7 +494,7 @@
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.
-==== 44. Achieve conditional logic with <property>. ====
+==== Achieve conditional logic with <property>. ====
New users to Ant often overlook this technique when searching for ways to
achieve conditional logic.
Defaulting the build.number property to zero if it is not set in a properties
file takes advantage of property immutability.
@@ -512,7 +512,7 @@
The server.name property could be set at the command-line, set from the
environment (with some indirection from <property name="server.name"
value="${env.COMPUTERNAME}"/>), or from a previously loaded properties file.
-==== 45. Use prefix to uniquely identify similar property names. ====
+==== Use prefix to uniquely identify similar property names. ====
Because of property immutability and name clash possibilities, the <property>
task allows prefixing all loaded properties.
To load two server configuration files with unique prefixes, use prefix.
@@ -525,7 +525,7 @@
=== Datatypes ===
-==== 46. Define reusable paths. ====
+==== Define reusable paths. ====
This eases build file maintenance. Adding a new dependency to the compile
classpath, in this example, automatically includes it in the test classpath.
@@ -546,7 +546,7 @@
This section deals with classpath issues within your build file.
-==== 47. Use explicit classpaths wherever possible. ====
+==== 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">
@@ -562,10 +562,10 @@
<arg value="${query}"/>
</java> }}}
-==== 48. Turn off includeAntRuntime on <javac>. ====
+==== 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.
-==== 49. Use the refid <property> variant for string representation of a path.
====
+==== Use the refid <property> variant for string representation of a path. ====
This can be useful for debugging purposes, or especially handy when invoking
Java programs with <apply>.
This example invokes ["JavaNCSS"] on a set of source files, producing an XML
output file.
@@ -592,19 +592,19 @@
=== Testing ===
-==== 50. Write tests first! ====
-{{{
+==== Write tests first! ====
+
While not directly related to Ant, we find it important enough to say
whenever we can.
- Corollary: if you can't do them first, do them second. }}}
+ Corollary: if you can't do them first, do them second.
-==== 51. Standardize test case names. ====
+==== Standardize test case names. ====
Name test cases *Test.java. In the <junit> task use <fileset dir="${test.dir}"
includes="**/*Test.class"/>. The only files named *Test.java are test cases
that can be run with JUnit. Name helper classes something else.
Another useful convention is naming base, typically abstract, test cases
*TestCase.
-==== 52. Provide visual and XML test results. ====
+==== Provide visual and XML test results. ====
Use <formatter type="brief" usefile="false"/> and <formatter type="xml"/>. The
brief formatter, without using a file, allows for immediate visual inspection
of a build indicating what caused the failure. The XML formatter allows for
reporting using <junitreport>.
-==== 53. Incorporate the single test case trick ====
+==== 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.
{{{
@@ -627,7 +627,7 @@
{{{
ant -Dtestcase=org.example.antbook.TroublesomeTest }}}
-==== 54. Fail builds when tests fail. ====
+==== 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:
{{{
@@ -651,7 +651,7 @@
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. ====
+==== 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.
{{{
@@ -671,7 +671,7 @@
=== Cross-platform issues ===
-==== 56. Launch even native scripts in a cross-platform manner. ====
+==== Launch even native scripts in a cross-platform manner. ====
Disabling the vmlauncher setting of <exec> executes through Ant?s launcher
scripts in ANT_HOME/bin.
{{{
@@ -682,7 +682,7 @@
=== Debugging ===
-==== 57. Log important information, at the appropriate level. ====
+==== 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.
{{{
@@ -691,7 +691,7 @@
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. ====
+==== Add a debug target. ====
Adding a debug target with no dependencies with an <echoproperties> can shed
light on possible misconfiguration.
{{{
@@ -701,7 +701,7 @@
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.
-==== 59. Increase Ant's verbosity level. ====
+==== Increase Ant's verbosity level. ====
By default, messages displayed to the console during Ant builds are only a
fraction of the messages generated by the Ant engine and tasks. To see all
logged output, use the -debug switch:
{{{
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
