Date: 2004-03-12T19:17:30
Editor: 203.121.47.163 <>
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
------------------------------------------------------------------------------
@@ -68,7 +68,8 @@
==== 8. Provide the <?xml?> directive. ====
Include the encoding if there are characters outside the ASCII range:
-{{{ <?xml version="1.0" encoding="iso-8859-1"?> }}}
+{{{
+<?xml version="1.0" encoding="iso-8859-1"?> }}}
==== 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:
@@ -88,7 +89,8 @@
One line also works for short begin and end pairs.
-{{{ <echo>build.dir = ${build.dir}</echo> }}}
+{{{
+ <echo>build.dir = ${build.dir}</echo> }}}
==== 11. 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.
@@ -182,18 +184,18 @@
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.
@@ -234,7 +236,8 @@
==== 25. Load environment variables with ?env.? prefix. ====
-{{{ <property env="env"/> }}}
+{{{
+ <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.
@@ -252,7 +255,8 @@
/> }}}
''lib.properties''
-{{{ xalan.jar=${lib.dir}/java/jakarta-xalan2/xalan.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)
@@ -278,16 +282,16 @@
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.
@@ -348,7 +352,7 @@
<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.
@@ -368,7 +372,8 @@
==== 33. 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"/> }}}
+{{{
+ <target name="help" depends="usage"/> }}}
==== 34. 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.
@@ -390,7 +395,9 @@
==== 36. Add an XSLT stylesheet to make build.xml browsable. ====
Right after the <?xml ... ?>, you can add a stylesheet reference, e.g.
-<?xml-stylesheet type="text/xsl" href="./ant2html.xsl"?>
+
+{{{
+<?xml-stylesheet type="text/xsl" href="./ant2html.xsl"?> }}}
Ant will ignore it, but if you open build.xml in a browser, it will show a
nicely formatted version of the script.
@@ -424,7 +431,8 @@
==== 40. 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 "/> }}}
+{{{
+ <property name="build.dir" location="build "/> }}}
==== 41. Handle creation and deletion of property referenced directories
individually. ====
Do not assume that hierarchically named properties refer to hierarchically
structured directories.
@@ -499,7 +507,8 @@
Setting properties differently depending on the server only requires a single
build file line.
-{{{ <property file="${server.name}.properties"/> }}}
+{{{
+ <property file="${server.name}.properties"/> }}}
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.
@@ -584,8 +593,9 @@
=== Testing ===
==== 50. 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. }}}
+{{{
+ 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. }}}
==== 51. 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.
@@ -614,7 +624,8 @@
During development, a single test case can be isolated and run from the
command-line:
-{{{ ant -Dtestcase=org.example.antbook.TroublesomeTest }}}
+{{{
+ ant -Dtestcase=org.example.antbook.TroublesomeTest }}}
==== 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:
@@ -663,7 +674,8 @@
==== 56. 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.
-{{{ <exec executable="script" vmlauncher="false" /> }}}
+{{{
+ <exec executable="script" vmlauncher="false" /> }}}
This will launch "script" on UNIX and "script.bat" on Windows OS's.
This assumes the UNIX script version does not have a suffix and the Windows
version has a supported suffix as defined in the PATHEXT environment variable.
This works because setting the vmlauncher attribute to false causes the command
to be executed through cmd.exe on Windows NT/2000/XP, antRun.bat on Windows 9x
and antRun on UNIX. Otherwise, with JVM's 1.3 and above, the command is
executed directly, bypassing any shell or command interpreter. (Submitted by
Bill Burton)
@@ -692,6 +704,7 @@
==== 59. 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:
-{{{ ant -debug }}}
+{{{
+ ant -debug }}}
The -debug switch generates an enormous amount of output. A good compromise is
the -verbose switch, which outputs more than the default informational level of
output, but less than the debugging output.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
