Posted on Friday, September 19th, 2008 at 4:43pm by Rob Wilkerson
This is the fifth in a series of posts meant to outline my Ant build script template. If you’re interested, it may be helpful to read the first four:
- Prelude
- Environment
- Process
- Why Two Files?
So at this point in this thing that I’ll loosely call a series, I’ve talked a lot, but in the put-up-or-shut-up debate, I’m still leaning heavily towards the shut up side. Today I hope to move that needle, at least a little bit, in the other direction.
Ant is the cat’s meow. The bee’s knees, if you’d rather. But then, I probably don’t need to sell anyone on the fact that I’m a fan. What Ant is not, though, is perfection. At least not without help. My build script requires three external task libraries to function properly. Technically, it’s two external libraries and one external dependency for a native task library, but at least we’re starting to talk code. First, a little information about the required tasks and then some information about making them work in the build script.
Fundamental to any build that includes deployment is the ability to move resources from one server to another. Unless absolutely necessary, I prefer to use SCP or, at the very least, SFTP. Both of these are better than FTP, but my infrastructure supports SCP, so that’s what I use. My build template also requires SSH, the protocol on which SCP is built, so there’s a nice two-for-the-price-of-one effect. Ant ships with SSH and SCP tasks but, perhaps counter intuitively, not with the library required to actually execute those tasks, jsch, a pure Java implementation of the SSH2 protocol.
There’s more information in a post I wrote over a year ago, but be sure to download the 0.1.29 version even though it’s not current. I’ve tried every version between 0.1.30 and 0.1.33 and they don’t work. Versions above 0.1.33 may work, but I can vouch for the fact that 0.1.29 works so it may be worth sticking with that.
For years now, I’ve been using Subversion as my source control solution. I’m taking some early stabs at learning git, but I’m still primarily a Subversion user. It’s not hard to figure out, I’m sure, that SvnAnt is a collection of Ant tasks for interacting with Subversion. This library supports the full range of commands available with Subversion (certainly every one that I need) in addition to the ability to connect using an installed svn executable or via JavaHL.
Antelope is a very useful – so useful that I actually think of it as critical – library of utility tasks designed to give Ant more power. The library includes conditionals, try/catch, grep, string manipulation and several other handy tasks that are used throughout my build script. Its capabilities are similar to those of AntContrib, but I think that Antelope offers more functionality and more options.
Including External Tasks
There’s an easy way to run external tasks in a build script and a hard way. I actually prefer the hard way. The easy way is to simply download the task library and extract its jar files anywhere in the system classpath. A typical approach would be to drop the jar files in the ANT_HOME/lib/ directory. The “hard” way is to extract the libraries anywhere at all and tell the script where they’re located. Sort of a lazy loading technique, I suppose. I prefer the latter method because it allows me to keep my external tasks, well, external.
I extract my external libraries to ~/Library/ant/tasks/ (again, let me state that this can be anywhere). I then set a few variables in my build.properties file:
tasklib.dir=/Users/me/Library/ant/tasks
<!--
Libraries associated with the SvnAnt task
-->
tasklib.svnant.tasks=${tasklib.dir}/svnant-1.0.0/lib/svnant.jar
tasklib.svnant.adapter=${tasklib.dir}/svnant-1.0.0/lib/svnClientAdapter.jar
tasklib.svnant.javahl=${tasklib.dir}/svnant-1.0.0/lib/svnjavahl.jar
<!--
Antelope only has one library
-->
tasklib.antelope.tasks=${tasklib.dir}/AntelopeTasks_3.4.2/
AntelopeTasks_3.4.2.jar
Note that any wrapping that occurred in this list of properties is a function of the limited display space on this site. Each property should appear on a single line in the properties file itself. In this code, any line that does not begin with “tasklib” (and is not a comment) is wrapped from the line above. I couldn’t think of a way to indicate that in the code without it being more, rather than less, confusing.
Once I have properties to indicate where my tasks reside, I can explicitly include them in my classpath and load the tasks by adding this code to my build.xml file:
<!-- load properties set in the build.properties file -->
<property file="build.properties" />
<!--
add external library file paths to the project classpath
-->
<path id="project.classpath">
<pathelement location="${tasklib.svnant.tasks}" />
<pathelement location="${tasklib.svnant.adapter}" />
<pathelement location="${tasklib.svnant.javahl}" />
<pathelement location="${tasklib.antelope.tasks}" />
</path>
<!-- make the svn tasks available -->
<taskdef resource="svntask.properties"
classpathref="project.classpath"
/>
<!-- make the antelope tasks available -->
<taskdef resource="ise/antelope/tasks/antlib.xml"
classpathref="project.classpath"
/>
That covers SvnAnt and Antelope, but the jsch library still needs to go somewhere. I treat that one a little differently, but the difference makes sense in my head. Since jsch is an external library that fulfills a dependency for a native task, I just drop the library in my ANT_HOME/lib/ directory. There it gets picked up automatically.
Alternatively, if I plan to run builds exclusively from within Eclipse (which is often the case), I might store it in ~/Library/ant/lib/ and tell Eclipse to find it there in its preferences. To set that preference:
- Go to Preferences > Ant > Runtime
- Select the Classpath tab
- Highlight Global Entries
- Select Add External JARs
- Navigate to jsch-0.1.29.jar, wherever its located
- Click Open in the file browser dialog
- Click OK in the Eclipse preferences dialog)
With external libraries in place and properly added to the classpath, previously unavailable or unusable tasks are now available for use. Up next: the unveiling.
ant, build
