[Ant Wiki] Updated: TheElementsOfAntStyle
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} }}}
-{{{
[Ant Wiki] Updated: TheElementsOfAntStyle
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.
-{{{ echobuild.dir = ${build.dir}/echo }}}
+{{{
+ echobuild.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.
+deployDeploy 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
[Ant Wiki] Updated: TheElementsOfAntStyle
Date: 2004-03-12T19:18:33
Editor: 203.121.47.163
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
--
@@ -68,7 +68,7 @@
8. 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.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
[Ant Wiki] Updated: TheElementsOfAntStyle
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 @@
{{{
echobuild.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
[Ant Wiki] Updated: TheElementsOfAntStyle
Date: 2004-03-12T19:24:39
Editor: 203.121.47.163
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
--
@@ -25,7 +25,8 @@
* Use comments liberally.
* Avoid dependencies on programs and JAR files outside the source tree: keep
everything you can under source code control for later re-creation of
development environments. That includes Ant itself, especially if you have
changed it in any way.
* Keep deployment usernames and passwords out of build files. Passwords
should change over time, and security is always an issue. Keep them in property
files out of source code control. If a password is required for a build
process, the user can be alerted to it being missing by using
-{{{fail message=Provide user.password unless=user.password/ }}}
+{{{
+fail message=Provide user.password unless=user.password/ }}}
* Never neglect false positive test case failures. Even if you know that
testWorstCase always fails, four months later someone else might have the
maintenance task and waste ages trying to find out why the build is reporting
errors. At best, fix them; otherwise exclude them from the test suite.
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.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
[Ant Wiki] Updated: TheElementsOfAntStyle
Date: 2004-03-12T19:26:40
Editor: 203.121.47.163
Wiki: Ant Wiki
Page: TheElementsOfAntStyle
URL: http://wiki.apache.org/ant/TheElementsOfAntStyle
no comment
Change Log:
--
@@ -86,7 +86,8 @@
One-line elements are acceptable.
This typically only applies to elements that combine their start and finish
tags into one.
-{{{ echo message=hello/ }}}
+{{{
+ echo message=hello/ }}}
One line also works for short begin and end pairs.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
