You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@ant.apache.org by Greg 'Cosmo' Haun <GH...@cenquest.com> on 2002/04/23 00:42:23 UTC
RE: The Elements of Ant Style - self-documenting build file
Here is an element of style, and also a disagreement RE: your example
element.
- 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="http://www.w3.org/1999/XSL/Transform" >
<xsl:output method="html" indent="yes"/>
<xsl:template match="project">
<html>
<body>
<h1><xsl:value-of select="./@name"/></h1>
<xsl:value-of select="./description"/>
<p />
<xsl:apply-templates select="target"/>
</body>
</html>
</xsl:template >
<xsl:template match="*[ @description | @taskname]">
<!-- use taskname if it exists, otherwise use the task element name
-->
<li><b>
<xsl:if test="not(@taskname)">
<xsl:value-of select="name()"/>
</xsl:if>
<xsl:value-of select="@taskname"/></b>
<xsl:text> </xsl:text>
<xsl:value-of select="@description"/>
</li>
</xsl:template>
<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>
<xsl:template match="*"/>
</xsl:stylesheet>
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
directly.
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
Email: ghaun@cenquest.com
Learn more about Cenquest collaborative e-learning at www.cenquest.com
> -----Original Message-----
> From: Erik Hatcher [mailto:jakarta-ant@ehatchersolutions.com]
> Sent: Thursday, April 18, 2002 5:22 PM
> To: ant-dev; ant-user@jakarta.apache.org
> 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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: The Elements of Ant Style - self-documenting build file
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
----- Original Message -----
From: "Greg 'Cosmo' Haun" <GH...@cenquest.com>
> Here is an element of style, and also a disagreement RE: your example
> element.
>
> - 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:
Thanks for the great tip and XSLT file to go along with it!
> 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
> directly.
This is not so much an issue now that there is an <echoproperties/> task.
You could put that in a "debug" target that you call when you want to see
how things are set (assuming things are set outside targets or in an "init"
target that "debug" depends on) and you can then see how things are
configured and work off that.
I agree that in a complex build it can be an overwhelming amount of
indirection going on, but I think the benefits of that indirection outweigh
the backtracking it takes to unwind it and figure out how things are set.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>