Ant: The Definitive Guide, 2nd Edition

Chapter 4. Deploying Builds

This chapter starts coverage of one of the things Ant does best: deployment. This chapter covers tasks to package applications for deployment like tar, gzip, and zip; tasks to prepare directories for deployment like delete and mkdir; and tasks to deploy applications like copy and move for local and network deployment, as well as ftp, telent, sshexec, and mail for remote deployment. You'll see other deployment-related tasks, such as touch to set the deployed files' modification dates to a specific value (as is done for commercial software deployments), fixcrlf to fix text file line endings (as in readme, .sh, .bat, .html, or .ini files) for different platforms, and more. Finally, you'll learn how to handle build automation, setting up builds to run on their own, at a schedule of your choosing.

Tip

There's more on deployment coming up in this book. Ant has a lot of support for deploying web applications, so much so that it'll take more than just this chapter to cover. Chapter 8 covers how to package and deploy web applications, including using get (used to send administrative commands to web servers remotely), serverdeploy, war, and other Ant tasks designed to load web applications to various servers. Chapter 8 and part of Chapter 9 also specifically discuss how to deploy to Enterprise JavaBean© (EJB) application servers.

Packaging Applications for Deployment

We're going to start with deployment tasks designed to package applications for deployment: tar, gzip, and zip. These are not the only way to package applications; the jar task was covered in Chapter 3 on Java Development, and the war task, a special form of the jar task for Web applications that makes allowances for files like the deployment descriptor web.xml, will be covered in Chapter 8.

Creating TAR Files

The tar task creates a TAR archive, handy for archiving files for distribution. This task is directory-based and, like other such tasks, forms an implicit FileSet that defines which files—relative to the basedir attribute setting—will be included in the archive.

If you set the compression attribute to gzip or bzip2, you can compress the output .tar file to the specified format. For instance, Example 4-1 compiles code and places the resulting Project.class file in a .tar.gz file, Project.tar.gz, by setting the compression attribute to gzip.

Example 4-1. Tarring a file (ch04/tar/build.xml)

<?xml version="1.0" ?>
<project default="main">

    <property name="message" value="Building the .tar.gz file." />
    <property name="src" location="source" />
    <property name="output" location="bin" />

    <target name="main" depends="init, compile, compress">
        <echo>
            ${message}
        </echo>
    </target>
  
    <target name="init">
        <mkdir dir="${output}" />
    </target>
  
    <target name="compile">
        <javac srcdir="${src}" destdir="${output}" />
    </target>
  
  <target name="compress">
        <tar 
            destfile="${output}/Project.tar.gz" 
            basedir="${output}" 
            includes="*.class" 
            compression="gzip"/>
  </target>
</project>

The attributes of this task appear in Table 4-1.

Table 4-1. The tar task's attributes

Attribute	Description	Required	Default
basedir	Specifies the directory from which to get the files to TAR.	No	Â
compression	Sets the compression method, if any. Legal values are none, gzip and bzip2.	No	none
defaultexcludes	Specifies if you want to use default excludes. Set to yes/no.	No	Default excludes are used.
destfile	Specifies the name of the TAR file you want to create.	Yes	Â
excludes	Specifies the patterns matching files to exclude, as a comma- or space-separated list.	No	No files (except default excludes) are excluded.
excludesfile	Specifies the name of a file where each line is a pattern matching files to exclude.	No	Â
includes	Specifies the patterns matching files to include, as a comma- or space-separated list.	No	All files are included.
includesfile	Specifies the name of a file where each line is a pattern matching files to include.	No	Â
longfile	Specifies how you want to handle long file paths (more than 100 characters). Possible values are truncate, fail, warn, omit and gnu.	No	warn

Here's another example that uses the Ant gzip task after the tar task to create Project.tar.gz:

<tar tarfile="${dist}/Project.tar" basedir="${output}"/>
<gzip zipfile="${dist}/Project.tar.gz" src="${dist}/project.tar"/>

This next example does the same thing, except that it excludes files from the beta directory and any todo.html files:

<tar tarfile="${dist}/Project.tar" basedir="${output}"
    excludes="beta/**, **/todo.html"/>
<gzip zipfile="${dist}/Project.tar.gz" src="${dist}/project.tar"/>

The tar task supports nested tarfileset elements. These are specially extended FileSet types that support all the fileset attributes, and the additional attributes you see in Table 4-2.

Tip

The tarfileset type gives you control over the access mode, username, and groupname to be applied to the TAR entries. This is handy, for example, when preparing archives for Unix systems where certain files need to have execute permissions.

Table 4-2. The additional tarfileset attributes

Attribute	Description	Required	Default
dirmode	Specifies a 3-digit octal string which gives the user and group using normal Unix conventions. Applies to directories only. Available since Ant 1.6.	No	755
fullpath	Using this attribute means the file in the fileset is written with this path in the compressed file.	No	Â
group	Specifies the group name for the TAR item.	No	Â
mode	Specifies a 3-digit octal string, which gives the user and group using normal Unix conventions. Applies to plain files only.	No	644
prefix	Specifies a path with which to prefix all files in the compressed file.	No	Â
preserveLeadingSlashes	Specifies if you want to preserve leading slashes (/ ) in filenames.	No	false
username	Specifies the username for this TAR item.	No	Â

This next, longer example uses GNU extensions for long paths and uses tarfileset elements to mark some files as executable (specifically, using Unix file mode 755, which means executable and readable by all, and writeable by the owner):

<tar longfile="gnu"
    destfile="${dist}" >
    <tarfileset dir="${bin}" mode="755" username="developer" group="ant">
        <include name="${bin}/bootstrap.sh"/>
        <include name="${bin}/build.sh"/>
    </tarfileset>
    <tarfileset dir="${dist}" username="developer" group="ant">
        <include name="${dist}/**"/>
        <exclude name="${dist}/*.sh"/>
    </tarfileset>
</tar>

Tip

Want to un-TAR a .tar archive? Ant has an untar task.

Compressing Using gzip and bzip2

The gzip and bzip2 tasks pack files using the GZip or BZip2 algorithms. Here's an example that GZips a .tar file:

<gzip src="Project.tar" destfile="Project.tar.gz"/>

Here's a similar example that BZips a .tar file:

<bzip2 src="Project.tar" destfile="Project.tar.bz2"/>

Tip

Ant supports gunzip and bunzip2 tasks for uncompressing archives.

The supported attributes for these tasks appear in Table 4-3.

Table 4-3. The gzip and bunzip2 tasks' attributes

Attribute	Description	Required
destfile	Specifies the file you want to create.	Exactly one of destfile or zipfile
src	Specifies the file you want to GZip or BZip.	Yes
zipfile	Deprecated. Use destfile.	Exactly one of destfile or zipfile

Creating ZIP Files

The zip task creates ZIP files, useful for packaging files for deployment. The zip task is easy enough to use; here's how to zip all files in the ${dist}/docs directory into docs.zip. If docs.zip doesn't exist, it's created; if it does, the files in it are updated:

<zip destfile="${dist}/docs.zip"
    basedir="${dist}/docs"
    update="true"
/>

This next example zips all files in the ${dist}/docs directory. Only .html files in the directory api will be zipped, and files with the name beta.html are excluded:

<zip destfile="${dist}/docs.zip"
    basedir="${dist}/docs"
    includes="api/**/*.html"
    excludes="**/beta.html"
/>

The attributes of this task appear in Table 4-4.

Tip

A JAR archive is a ZIP file with a manifest; if you don't want a manifest in a JAR file, use zip instead of jar.

Table 4-4. The zip task's attributes

Attribute	Description	Required	Default
basedir	Specifies the directory where the files you want to zip are.	No	Â
compress	Specifies that you don't want to store data but want to compresses it.	No	true
defaultexcludes	Specifies whether you want default excludes to be used or not (yes/no).	No	Default excludes are used
destfile	Specifies the ZIP file you want to create.	Exactly one of destfile or zipfile.	Â
duplicate	Specifies what you want to do when a duplicate file is found. Valid values are add, preserve, and fail.	No	add
encoding	Specifies the character encoding you want to use inside the ZIP file.	No	The platform's default character encoding.
excludes	Specifies the patterns matching files to exclude, as a comma- or space-separated list.	No	No files (except default excludes) are excluded.
excludesfile	Specifies the name of a file where each line is a pattern matching files to exclude.	No	Â
filesonly	Stores only file entries.	No	false
includes	Specifies the patterns matching files to include, as a comma- or space-separated list.	No	All files are included.
includesfile	Specifies the name of a file where each line is a pattern matching files to include.	No	Â
keepcompression	Preserves the compression as it has been in archives you're compressing instead of using the compress attribute. Available since Ant 1.6.	No	false
update	Specifies whether you want to update or overwrite the destination file in case it exists.	No	false
whenempty	Specifies what you want to do when no files match. Possible values are fail, skip, and create.	No	skip
zipfile	Deprecated. Use destfile.	One of destfile or zipfile	Â

This task supports any number of nested fileset elements to specify the files to be included in the ZIP file. The zip task supports any number of nested zipfileset elements, which support all the attributes of fileset (see Table 2-8) as well as the ones you see in Table 4-5.

Table 4-5. The additional zipfileset attributes

Attribute	Description	Required	Default
dirmode	Specifies a 3-digit octal string, which gives the user and group using normal Unix conventions. Applies to directories only.	No	755
filemode	Specifies a 3-digit octal string, which gives the user and group using normal Unix conventions. Applies to plain files only.	No	644
fullpath	Using this attribute means that the file in the fileset is written with this path in the compressed file.	No	Â
prefix	Specifies a path to with which prefix all files in the compressed file.	No	Â
src	Specifies a ZIP file instead of a directory as the source of files.	No	Â

You can nest zipgroupfileset elements in a zip task. These elements allow you to add multiple ZIP files in the archive. The attributes for the zipgroupfileset type are the same as for the fileset type and include the extra attributes for zipfileset elements (see Table 4-5).

Tip

Because the zip task forms an implicit FileSet (dir becomes basedir), you can use nested include, exclude, and patternset elements.

This example zips all files in the docs directory into the docs/guide directory in the archive, adds the file readme.txt in the current directory as docs/readme.txt, and includes all the html files in examples.zip under docs/examples:

<zip destfile="${dist}/docs.zip">
    <zipfileset dir="docs" prefix="docs/guide"/>
    <zipfileset dir="${dist}" includes="readme.txt" fullpath="docs/readme.txt"/>
    <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
</zip>

Tip

Ant provides an unzip task if you want to decompress ZIP files.

Fixing Carriage Returns

If you've ever deployed documentation files from Unix to Windows or Windows to Unix, you've probably run into problems with line endings. Lines in Unix text files typically end with a newline (/n) while those in DOS and Windows typically end with a carriage return/line feed pair (/r/n). To modify text files before deploying them to other operating systems, use fixcrlf. Like other directory-based Ant tasks, this task forms an implicit FileSet and supports all attributes of fileset (dir becomes srcdir) as well as the nested include, exclude and patternset elements.

Say, for example, that you wanted to convert the end of line characters in Unix shell scripts (*.sh) to be uploaded from Windows to a Unix server to a linefeed, and remove any DOS-style end-of-file (EOF) characters (^Z). You could do that like this:

<fixcrlf srcdir="${src}"
    eol="lf" 
    eof="remove"
    includes="**/*.sh"
/>

Here's how you might go the other way, replacing all end-of-line (EOL) characters with a cr-lf pair in DOS batch (.bat) files in preparation to downloading them to Windows:

<fixcrlf srcdir="${src}"
    eol="crlf"
    eof="add"
    includes="**/*.bat"
/>

This example converts all *.txt files according to the convention of the host operating system and replaces tabs with spaces:

<fixcrlf srcdir="${src}"
    tab="remove"
    includes="**/*.txt"
/>

Tip

As demonstrated by the previous example, fixcrlf is good for removing or inserting tabs. That's useful because some software (e.g., Make) is finicky about tabs.

The attributes of this task appear in Table 4-6.

Table 4-6. The fixcrlf task's attributes

Attribute	Description	Required	Default
cr	Deprecated. Use eol.	No	Â
defaultexcludes	Specifies if you want to use default excludes or not Set to yes/no.	No	Default excludes are used.
destDir	Specifies where you want the modified files.	No	The value of srcDir.
encoding	Specifies the encoding of the files you're working on.	No	The default JVM encoding.
eof	Specifies how you want to handle DOS end-of-file (^Z) characters. Possible values are: add Makes sure an EOF character is at the end of the file. asis Leaves EOF characters alone. remove Removes any EOF character found at the end.	No	The default is based on platform. In Unix, the default is remove. For Windows/DOS systems, the default is asis.
eol	Specifies how you want to handle end-of-line (EOL) characters. Possible values are: asis Leaves EOL characters alone. cr Converts all EOLs to a single CR. lf Converts all EOLs to a single LF. crlf Converts all EOLs to the pair CRLF. mac Converts all EOLs to a single CR. unix Converts all EOLs to a single LF. dos Converts all EOLs to the pair CRLF.	No	The default is based on platform. In Unix, the default is lf. For Windows/DOS systems, the default is crlf. For Mac OS, the default is cr.
excludes	Specifies the patterns matching files to exclude, as a comma- or space-separated list.	No	Â
excludesfile	Specifies the name of a file where each line is a pattern matching files to exclude.	No	Â
fixlast	Specifies whether you want to add an EOL to the last line of a processed file. Available since Ant 1.6.1.	No	true
includes	Specifies the patterns matching files to include, as a comma- or space-separated list.	No	Â
includesfile	Specifies the name of a file where each line is a pattern matching files to include.	No	Â
javafiles	Specifies if the file is a Java code file. Used with the tab attribute. Set to yes/no.	No	no
srcDir	Specifies where to find the files you want to fix.	Yes	Â
tab	Specifies how you want to handle tab characters. Possible values are: add Converts sequences of spaces span a tab stop to tabs. asis Leaves tab and space characters alone. remove Converts tabs to spaces.	No	asis
tablength	Specifies the tab character interval. Possible values range from 2 to 80.	No	8

Warning

The output file is only written if it is a new file, or if it differs from the existing file. The idea is to prevent bogus rebuilds based on unchanged files that have been regenerated by this task.

Checking File Contents Using Checksums

A checksum is a numerical value corresponding to the contents of a file, and it can tell you if the copy of the file you've deployed is a good copy. This task lets you create an MD5 checksum for a file or set of files. Here's an example using this task; in this case, I'm creating an MD5 checksum for Project.jar, which will be stored in a file named Project.jar.MD5:

<checksum file="Project.jar"/>

You can generate a similar checksum for the file after it's been deployed to check if it's OK.

Build files can be used to verify checksum values when testing a deployment; for example, you can generate an MD5 checksum for Project.jar, compare that value to a value you've hard-coded into a property named checksum, and set the property checksumOK if the two values match:

<checksum file="Project.jar" property="${checksum}" verifyProperty="checksumOK"/>

You can see the attributes of the checksum task in Table 4-7.

Table 4-7. The checksum task's attributes

Attribute	Description	Required	Default
algorithm	Specifies the algorithm you want to use to compute the checksum.	No	MD5
file	Specifies the file you want to generate the checksum for.	One of file or at least one nested fileset element.	Â
fileext	Specifies the extension of the file for the generated checksum.	No	Defaults to the algorithm name being used.
forceoverwrite	Specifies whether you want to overwrite existing files.	No	no
property	If verifyproperty is not set, property specifies the name of the property to hold the checksum value. If verifyproperty is set, property specifies the actual checksum value you expect.	No	Â
provider	Specifies the algorithm provider.	No	Â
readbuffersize	Specifies the size of the buffer the task should use when reading files, in bytes.	No	8192
todir	Specifies the directory where you want checksums to be written. Available since Ant 1.6.	No	Checksum files are written to the same directory as the source files.
totalproperty	Specifies the name of the property that you want to hold a checksum of all the generated checksums and file paths. Available since Ant 1.6.	No	Â
verifyproperty	Specifies the name of the property to be set true or false depending upon whether the generated checksum matches the existing checksum.	No	Â

Tip

The checksum task can contain nested fileset elements. By now, this should be old hat to you.

Setting Creation Time and Date

When you're deploying files, you can set the creation date and time of those files to a single value to make the deployment look more professional (as you'll usually see with commercial software). The touch task will do this for you; besides setting the creation time and date for a single file, you can do the same thing for whole directories of files if you include a fileset.

If you only specify a single file, its modification time and date is set to the current time and date:

<touch file="Project.jar"/>

Here's an example that sets the modification time and date of all the files in ${src} to January 1, 2005, at 5:00 PM:

<touch datetime="01/01/2005 5:00 pm">
    <fileset dir="${src}"/>
</touch>

Tip

If the file you're touching doesn't exist, touch will create it for you, which is one of the few ways you can use Ant to create empty files (you can create files with text in them with the echo task, using the file attribute). Want to give the file a name that's guaranteed to be unique? Use Ant's tempfile task—for example, <tempfile property="temp.file" /> will store the unique name of a file in the temp.file property, and <touch file="${temp.file}" /> will create that file.

You can see the attributes of this task in Table 4-8.

Table 4-8. The touch task's attributes

Attribute	Description	Required
datetime	Specifies the new modification time of the file. Use the formats MM/DD/YYYY HH:MM AM_or_PM or MM/DD/YYYY HH:MM:SS AM_or_PM.	No
file	Specifies the name of the file whose time and/or date information you want to change.	Yes, unless you use a nested fileset element.
millis	Specifies the new modification time of the file, given in epoch milliseconds (that is, since midnight, Jan 1, 1970).	No

The touch task can contain nested fileset elements to touch multiple files at once.