Archiving Task

Archiving Tasks

For each of the supported archiving formats there is a correspondig archiving task. These tasks are supersets of the core tar and zip tasks but don't share any code with them. Note that some attributes may use different defaults from the core tasks or some functionality may be available in different ways than with the core tasks - see the tar and zip documentation for details.

If some of the nested resources that shall be added to the archive are archive resources themselves - i.e. they come from one of this Antlib's entry or fileset resources or are core tarentry or zipentry resources or returned by a core tarfileset or zipfileset - the task will try to preserve the entry's permissions and as many other attributes of the entry as the archiving format supports.

All archiving tasks share the following attributes and nested elements:

Parameters

Attribute	Description	Required
dest	the destination resource to create.	Exactly one of the two or a nested dest element.
destfile	the destination file to create.	Exactly one of the two or a nested dest element.
encoding	The character encoding to use for filenames inside the archive. For a list of possible values see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html. The magic value `native-encoding` can be used to explicitly select the platform's default character encoding. Defaults to the platform's default character encoding. Currently ignored by all but the tar (since Compress Antlib 1.2), cpio (since Compress Antlib 1.3) and zip tasks.	No
filesonly	Store only file entries, defaults to true	No
preserve0permissions	when updating an archive or adding entries from a different archive Ant will assume that a Unix permissions value of 0 (nobody is allowed to do anything to the file/directory) means that the permissions haven't been stored at all rather than real permissions and will instead apply its own default values. Set this attribute to true if you really want to preserve the original permission field. Default is false.	No
roundup	Whether the file modification times will be rounded up taking the timestamp granularity of the archiving format into account. ZIP archives store file modification times with a granularity of two seconds, the other formats use a single second as granularity. Times will either be rounded up or down. If you round down, the archive will always seem out-of-date when you rerun the task, so the default is to round up. Rounding up may lead to a different type of problems like JSPs inside a web archive that seem to be slightly more recent than precompiled pages, rendering precompilation useless. Defaults to true.	No
preserveLeadingSlashes	Indicates whether leading `/'s should be preserved in the file names. Default is `false`.	No
duplicate	behavior when a duplicate entry is found. Valid values are "add", "preserve", and "fail". The default value is "fail".	No
whenempty	behavior when no files match. Valid values are "fail" and "skip". Default is "fail".	No
mode	One of "create", "force-create", "replace", "force-replace" or "update" - see below. Default is "create".	No

mode attribute

There are three basic modes a task can be in:

create - creates an archive that will contain all resources that have been specified as nested resources.
replace - creates an archive that will contain all resources that have been specified as nested resources. If the dest archive exists before running the task, any resource of the original archive that doesn't match a resource specified as nested resource will be preserved.
update - creates an archive that will contain all resources that have been specified as nested resources that are newer than their corresponding entries in the dest archive - or that don't exist in the dest archive. If the dest archive exists before running the task, any resource of the original archive that doesn't match a resource specified as nested resource or is more recent than the nested resource will be preserved.

If the dest archive doesn't exist before running the task, all modes behave the same. If it does exist, create may remove existing entries and replace may replace entries that are more recent than the specified source resources.

All three modes will first check whether the dest archive is "out of date". An archive is considered out of date if

it doesn't exist.
it exists but for at least one source resource there is no matching entry in the dest resource.
the matching entry for at least one source resource is older than the source resource.

Neither of the basic modes will modifiy the dest archive if it is not "out of date". For the create and replace modes there are variants force-create and force-replace that will bypass the "out of date" check and always replace (entries in) existing archives.

Parameters specified as nested elements

dest

Accepts any resource or single element resource collection as nested element.

The specified resource will be used as dest.

any resource or resource collection

This specifies the files and directories that shall be added to the archive.

Ar

An archiving task creating archives of the AR format.

The AR format is pretty limited, by default it can only store file names up to 16 characters and not store directories at all. It is not possible to set the filesonly attribute to true for the ar task.

Attribute	Description	Required
format	Ar format for entries with names longer than 16 characters. Supported values are "ar" which doesn't support entries of that length and results in a build failure and "bsd".	No, default is "ar"

Cpio

An archiving task creating archives of the CPIO format.

This task supports the following additional attributes:

Attribute	Description	Required
format	CPIO format for the archive to create. One of "binary", "old-ascii", "new-ascii". "odc" can be used as a synonym for "old-ascii".	No, default is "binary"
blocksize	Block size for the archive. Must be a positive number.	No, default is 512.

SevenZ

Since Compress Antlib 1.3

An archiving task creating archives of the 7z format. As of Commons Compress 1.8 this task only supports writing unencrypted archives.

Parameters

Attribute	Description	Required
contentCompression	compression algorithm to use for entry contents. As of Commons Compress 1.8 this can be "LZMA2", "BZIP2", "DEFLATE" or "COPY" where "COPY" means no compression at all.	No, default is LZMA2.
keepcompression	For entries coming from existing archives (like nested sevenzfilesets or while updating the archive), keep the compression as it has been originally instead of using the contentCompression attribute. Defaults to false. since 1.5	No

Parameters specified as nested elements

contentMethod

Specifies and configures a content method to use when creating an archive. Multiple methods build a pipeline where the first method is used to process the original input and its output is sent ot the next method until the final output is written to the archive.

As of Commons Compress 1.8 in addition to the compression methods "LZMA2", "BZIP2", "DEFLATE" or "COPY" filters can be used. Names of filter methods end with "_FILTER" and must not be used as final method - this is neither enforced by this antlib or Commons Compress but 7z may fail to extract the archive. As of Commons Compress 1.8 the supported filters are "BCJ_X86_FILTER", "BCJ_PPC_FILTER", "BCJ_IA64_FILTER", "BCJ_ARM_FILTER", "BCJ_ARM_THUMB_FILTER", "BCJ_SPARC_FILTER" and "DELTA_FILTER". The "BCJ" filters may improve compression ratio for executables for a given platform.

Some methods support additional options, "DELTA_FILTER" even requires one. The interpretation or even the type of an option depends on the method - see Commons Compress' documentation. As of version 1.5 only numeric options are supported.

Parameters of contentMethod

Attribute	Description	Required
method	method to use.	Yes.
option	Numeric option for this method.	No

Tar

An archiving task creating archives of the TAR format.

This task does not support the compression attribute of the core task. You should use a compressing task with a tar task as nested element instead.

This task supports the following additional attributes:

Attribute	Description	Required
format	Tar format to use. See the section below. Supported values are "ustar", "oldgnu", "gnu", "star" and "pax".	No, default is "ustar"

Tar format

Over time the original tar format has seen various extensions and revisions. The Apache Commons Compress library supports the original format (called "ustar") and some extensions added later, but not all of them. It supports a subset of features offered by the POSIX 1003.1 standard (often referred to as PAX), but this support is not complete.

The Compress Antlib follows Commons Compress' support. Currently the format affects two areas, files bigger than 8 GiB or that need other numeric values not fitting into the traditional tar headers and entries with names longer than 100 characters. For Commons Compress these areas can be configured separately while the Antlib chooses them based on a single format attribute.

Format Attribute	Numeric values too big like files bigger 8GiB	Entry names longer 100 characters	Notes
ustar	Not supported, throws an exception.	Not supported, throws an exception.	Default.
oldgnu	Not supported, throws an exception.	Uses a GNU tar specific extension.	Created archives may be unreadable on MacOS X, Solaris or with other non-GNU implementations of tar.
star	Uses an extension first introduced by Jörg Schilling's star and later adopted by GNU tar and BSD tar.	Uses a PAX extended header as defined by POSIX 1003.1.	Created archives will be readable by star and modern versions of GNU tar and BSD tar.
gnu		Uses a GNU tar specific extension.	Created archives may be unreadable on MacOS X, Solaris or with other non-GNU implementations of tar. The archives are similar to what GNU tar would create by default.
pax	Uses use a PAX extended header as defined by POSIX 1003.1.		Created archives will be readable by all modern implementations of tar.

Examples

<cmp:tar destfile="${dist}/manual.tar"
    xmlns:cmp="antlib:org.apache.ant.compress">
  <fileset dir="htdocs/manual"/>
<cmp:tar/>
<cmp:gzip destfile="${dist}/manual.tar.gz"
    src="${dist}/manual.tar"
    xmlns:cmp="antlib:org.apache.ant.compress"/>

tars all files in the htdocs/manual directory into a file called manual.tar in the ${dist} directory, then applies the gzip task to compress it.

<cmp:tar destfile="${dist}/manual.tar"
    xmlns:cmp="antlib:org.apache.ant.compress">
  <fileset dir="htdocs/manual"
     excludes="mydocs/**, **/todo.html"
  />
<cmp:tar/>

tars all files in the htdocs/manual directory into a file called manual.tar in the ${dist} directory. Files in the directory mydocs, or files with the name todo.html are excluded.

<cmp:tar destfile="${basedir}/docs.tar"
    preserveLeadingSlashes="true">
    xmlns:cmp="antlib:org.apache.ant.compress">
  <cmp:tarfileset dir="${dir.src}/docs"
              fullpath="/usr/doc/ant/README">
    <include name="readme.txt"/>
  </cmp:tarfileset>
  <cmp:tarfileset dir="${dir.src}/docs"
              prefix="/usr/doc/ant">
    <include name="*.html"/>
  </cmp:tarfileset>
</cmp:tar>

Writes the file docs/readme.txt as /usr/doc/ant/README into the archive. All *.html files in the docs directory are prefixed by /usr/doc/ant, so for example docs/index.html is written as /usr/doc/ant/index.html to the archive.

<cmp:tar format="oldgnu"
     destfile="${dist.base}/${dist.name}-src.tar">
  <tarfileset dir="${dist.name}/.." filemode="755" username="ant" group="ant">
    <include name="${dist.name}/bootstrap.sh"/>
    <include name="${dist.name}/build.sh"/>
  </tarfileset>
  <tarfileset dir="${dist.name}/.." username="ant" group="ant">
    <include name="${dist.name}/**"/>
    <exclude name="${dist.name}/bootstrap.sh"/>
    <exclude name="${dist.name}/build.sh"/>
  </tarfileset>
</cmp:tar>

This example shows building a tar which uses the GNU extensions for long paths and where some files need to be marked as executable (mode 755) and the rest are use the default mode (read-write by owner). The first fileset selects just the executable files. The second fileset must exclude the executable files and include all others.

<cmp:gzip destfile="release.tar.gz" xmlns:cmp="antlib:org.apache.ant.compress">
  <cmp:tar>
    <cmp:zipfileset src="release.zip"/>
  </cmp:tar>
</cmp:gzip>

Re-packages a ZIP archive as a GZip compressed tar archive. If Unix file permissions have been stored as part of the ZIP file, they will be retained in the resulting tar archive.

Zip

An archiving task creating archives of the ZIP format.

The discussion about encodings in the core zip task manual applies to this task as well.

Note the following attributes have default values different from the core zip task: filesonly, whenempty and duplicate. The core task's compress attribute isn't available for this task, use the level attribute instead where a level of 0 corresponds to no compression and not specifying a level at all to default compression.

This task supports the following additional attributes:

Attribute	Description	Required
level	Non-default level at which file compression should be performed. Valid values range from 0 (no compression/fastest) to 9 (maximum compression/slowest).	No
comment	Comment to store in the archive.	No
keepcompression	For entries coming from existing archives (like nested zipfilesets or while updating the archive), keep the compression as it has been originally instead of using the level attribute. Defaults to false.	No
useLanguageEncodingFlag	Whether to set the language encoding flag if the encoding is UTF-8. This setting doesn't have any effect if the encoding is not UTF-8. See also the discussion in the core task's manual. Default is true.	No
createUnicodeExtraFields	Whether to create unicode extra fields to store the file names a second time inside the entry's metadata. Possible values are "never", "always" and "not-encodable" which will only add Unicode extra fields if the file name cannot be encoded using the specified encoding. See also the discussion in the core task's manual. Default is "never".	No
fallbacktoUTF8	Whether to use UTF-8 and the language encoding flag instead of the specified encoding if a file name cannot be encoded using the specified encoding. See also the discussion in the core task's manual. Default is false.	No
zip64Mode	Controls whether Zip64 extended information is written to the archive. In order to store entries bigger than 4GB or more than 65536 entries inside an archive, so called Zip64 extensions must be used. An archive that uses such extensions may not be readable by all unarchivers. The possible modes are "always", "never" and "as-needed". The default is "as-needed" which enables Zip64 extensions if a resource is added to the archive whose size is known to exceed 4GB or if there are more than 65536 entries. "as-needed" does not work for resources of unknown size (like URL-resources), if you try to archive such resources, the default will be "never" instead of "as-needed". If the mode is "never" and the resource actually exceeds the limit, the build will fail.	No

Examples

<cmp:zip destfile="${dist}/manual.zip
    xmlns:cmp="antlib:org.apache.ant.compress"">
  <fileset dir="htdocs/manual"/>
<cmp:zip/>

zips all files in the htdocs/manual directory into a file called manual.zip in the ${dist} directory.

<cmp:zip destfile="${dist}/manual.zip"
    xmlns:cmp="antlib:org.apache.ant.compress"">
  <fileset dir="htdocs/manual"
       excludes="mydocs/**, **/todo.html"
    />
</cmp:zip>

zips all files in the htdocs/manual directory. Files in the directory mydocs, or files with the name todo.html are excluded.

<cmp:zip destfile="${dist}/manual.zip"
    xmlns:cmp="antlib:org.apache.ant.compress"">
  <fileset dir="htdocs/manual"
       includes="api/**/*.html"
       excludes="**/todo.html"
    />
</cmp:zip>

zips all files in the htdocs/manual directory. Only html files under the directory api are zipped, and files with the name todo.html are excluded.

<cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
  <fileset dir="htdocs/manual"/>
  <fileset dir="." includes="ChangeLog.txt"/>
</cmp:zip>

zips all files in the htdocs/manual directory, and also adds the file ChangeLog.txt in the current directory. ChangeLog.txt will be added to the top of the ZIP file, just as if it had been located at htdocs/manual/ChangeLog.txt.

<cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
  <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
  <cmp:zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/>
  <cmp:zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
</cmp:zip>

zips all files in the htdocs/manual directory into the docs/user-guide directory in the archive, adds the file ChangeLog27.txt in the current directory as docs/ChangeLog.txt, and includes all the html files in examples.zip under docs/examples. The archive might end up containing the files:

    docs/user-guide/html/index.html
    docs/ChangeLog.txt
    docs/examples/index.html

The code

<cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
  <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
  <cmp:archives>
    <zips>
      <fileset dir="." includes="examples*.zip"/>
    </zips>
  </cmp:archives>
</cmp:zip>

zips all files in the htdocs/manual directory into the docs/user-guide directory in the archive and includes all the files in any file that maches examples*.zip, such as all files within examples1.zip or examples_for_brian.zip. The same can be achieved with

<cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
  <mappedresources>
    <fileset dir="htdocs/manual"/>
    <globmapper from="*" to="docs/user-guide/*"/>
  </mappedresources>
  <archives>
    <zips>
      <fileset dir="." includes="examples*.zip"/>
    </zips>
  </archives>
</cmp:zip>

The next example

<cmp:zip dest="release.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
  <cmp:tarfileset src="release.tar"/>
</cmp:zip>

re-packages a TAR archive as a ZIP archive. If Unix file permissions have been stored as part of the TAR file, they will be retained in the resulting ZIP archive.