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