[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. -{{{}}} +{{{ +}}} One line also works for short begin and end pairs. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
[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 -{{{ }}} +{{{ + }}} * 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: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 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 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 directive. + Provide the directive. Include the encoding if there are characters outside the ASCII range: {{{ }}} - 9. Use consistent indentation. + Use consistent indentation. Keep at the very left edge, along with the tag. Two or four spaces is typical, no hard tabs. Keep closing elements aligned with opening elements, as in here: {{{ @@ -82,7 +82,7 @@ .. }}} - 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. {{{}}} @@ -92,7 +92,7 @@ {{{ build.dir = ${build.dir} }}} - 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
[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 directive. Include the encoding if there are characters outside the ASCII range: -{{{ +{{{ }}} 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: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 directive. Include the encoding if there are characters outside the ASCII range: -{{{ }}} +{{{ + }}} 9. Use consistent indentation. Keep at the very left edge, along with the tag. Two or four spaces is typical, no hard tabs. Keep closing elements aligned with opening elements, as in here: @@ -88,7 +89,8 @@ One line also works for short begin and end pairs. -{{{ build.dir = ${build.dir} }}} +{{{ + build.dir = ${build.dir} }}} 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 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 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. -{{{ }}} +{{{ + }}} 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. +distDistribution directory. +docsDocumentation files stored in their presentation format.
[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 at the very left edge, along with the tag. Two or four spaces is typical, no hard tabs. Keep closing elements aligned with opening elements, as in here: -{{{ }}} -{{{ }}} -{{{.. }}} -{{{ }}} -{{{.. }}} -{{{ }}} +{{{ + + +.. + +.. + }}} 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. -{{{ }}} +{{{ + }}} 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: , , and . 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 . -{{{ }}} -{{{ }}} +{{{ + + -{{{ }}} -{{{ }}} -{{{ }}} -{{{ }}} - -{{{ }}} -{{{ }}} -{{{ }}} + + -{{{ }}} + + + + + + + }}} Some exceptions apply, such as compiling and using a custom task in the same build - this requires the 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. -{{{ }}} -{{{ }}} -{{{ }}} +{{{ + + + }}} For commonly used tasks, such as , establish a preferred ordering of attributes and be consistent across projects: -{{{ }}} -{{{}}} +{{{ + }}} + 15. Use XML entity references to include common fragments. -{{{ }}} -{{{ }}} -{{{]> }}} -{{{ }}} +{{{ + + +]> + -{{{ &properties; }}} + &properties; -{{{ }}} + }}} 15.1 Ant 1.6 adds an 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 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. }}}