Section 4.1. Packaging Applications for Deployment


4.1. 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.

4.1.1. 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 filesrelative to the basedir attribute settingwill 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="/books/1/253/1/html/2/${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="/books/1/253/1/html/2/${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.

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>

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


4.1.2. 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="/books/1/253/1/html/2/Project.tar" destfile="Project.tar.gz"/>

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

<bzip2 src="/books/1/253/1/html/2/Project.tar" destfile="Project.tar.bz2"/>

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


4.1.3. 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.

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).

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="/books/1/253/1/html/2/examples.zip" includes="**/*.html" prefix="docs/examples"/> </zip>

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


4.1.4. 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" />

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


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.


4.1.5. 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

 


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


4.1.6. 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>

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 taskfor 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.



    Ant. The Definitive Guide
    Ant: The Definitive Guide, 2nd Edition
    ISBN: 0596006098
    EAN: 2147483647
    Year: 2003
    Pages: 115
    Authors: Steve Holzner

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net