ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg 'Cosmo' Haun <>
Subject RE: The Elements of Ant Style - self-documenting build file
Date Mon, 22 Apr 2002 22:42:23 GMT
Here is an element of style, and also a disagreement RE: your example

- Use description attributes to comment your build file.

All tasks have a description attribute, as do targets and projects.  By
using them, you can build documentation for your build process using
something like this XSL transform:

<?xml version="1.0" ?>
<!-- Create documentation from an ant build file  -->
<xsl:stylesheet version="1.0"
xmlns:xsl="" >
	<xsl:output method="html"  indent="yes"/>
	<xsl:template match="project">
		<h1><xsl:value-of select="./@name"/></h1>
			<xsl:value-of select="./description"/>
			<p />
			<xsl:apply-templates select="target"/>
	</xsl:template >
	<xsl:template match="*[ @description | @taskname]">
	<!-- use taskname if it exists, otherwise use the task element name
		<xsl:if test="not(@taskname)">
				<xsl:value-of select="name()"/>
		<xsl:value-of select="@taskname"/></b>
		<xsl:text> </xsl:text>
		<xsl:value-of select="@description"/>
	<xsl:template match="//target">
		<b><xsl:value-of select="@name"/></b> - 
		<xsl:value-of select="@description"/>
		<ul><xsl:apply-templates select="./*"/></ul>
		<p />
	<xsl:template match="*"/>

As for your example of building paths up from previously defined properties,
I used to use that strategy but found with complex builds it took too many
steps to figure out exactly what path corresponds to a property.  With
built-up properties, you have to look at the property definition of the
property in question, then the definitions of the properties used appearing
in that defintion, and so on and so on. I now prefer to define the
properties directly, so that when I'm looking at a property I simply do a
text search for the property name and since it's at the top of my build
file, its full definition shows up instantly.  If I need to change a base
directory, I simply use global search and replace.  It doesn't sound as
elegant, but I breath a sigh of relief when I find a property defined

I suppose the direct technique is most useful when you have a fragmented
heirarchy (files from multiple servers/shares, more like a forest than a
tree) whereas built-up properties might be best when you have a nice tree
structure to the files your build is using.

Gregory Cosmo Haun
Architect, Interactive Development
Cenquest, Inc.

Phone: 503.276.7943

Learn more about Cenquest collaborative e-learning at

> -----Original Message-----
> From: Erik Hatcher []
> Sent: Thursday, April 18, 2002 5:22 PM
> To: ant-dev;
> Subject: The Elements of Ant Style
> The Ant book that I'm co-authoring is entering its last phase 
> of development
> and we would like to involve the entire Ant community in our 
> efforts. The [...]
  Here is an example:
> - Build paths up from previously defined properties rather 
> than directly.
> Don't do this:
>   <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"/>

To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message