blob: 973a565363ee1e0ea7fe18bd8efed993e812dadd [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Apache Compress Antlib User Manual</title>
</head>
<body>
<h2>Apache Compress Antlib User Manual</h2>
<p>This Antlib contains tasks and resources that provide
compression/uncompression and archival/unarchival capabilities
based on <a href="https://commons.apache.org/compress/">Apache
Commons Compress</a>. Using Apache Commons Compress 1.16 this
Antlib supports gzip, bzip2, lzma standalone, xz, .Z, DEFLATE, DEFLATE64,
Snappy, LZ4, Brotli, Zstandard and pack200 compression and ar, arj, cpio,
7z, Unix dump, tar and zip archives. Support for arj, .Z,
Brotli, DEFLATE64 and dump is read-only. 7z can only be used on filesystem
resources.</p>
<h3>Known Limitations</h3>
<p>Reading AR archives from non-filesystem resources currently
fails for reasons that haven't been investigated, yet. Most
likely the problem is within Apache Commons Compress.</p>
<h3>Tasks and Types</h3>
<p>This Antlib contains the following tasks:</p>
<ul>
<li><a href="archive.html#ar">ar</a></li>
<li><a href="unpack.html#bunzip2">bunzip2</a></li>
<li><a href="pack.html#bzip2">bzip2</a></li>
<li><a href="archive.html#cpio">cpio</a></li>
<li><a href="pack.html#deflate">deflate</a></li>
<li><a href="unpack.html#gunzip">gunzip</a></li>
<li><a href="pack.html#gzip">gzip</a></li>
<li><a href="pack.html#lz4">lz4</a></li>
<li><a href="pack.html#lzma">lzma</a></li>
<li><a href="pack.html#pack200">pack200</a></li>
<li><a href="pack200normalize.html">pack200normalize</a></li>
<li><a href="archive.html#sevenz">sevenz</a></li>
<li><a href="pack.html#snappy">snappy</a></li>
<li><a href="archive.html#tar">tar</a></li>
<li><a href="expand.html#un7z">un7z</a></li>
<li><a href="expand.html#unar">unar</a></li>
<li><a href="expand.html#unarj">unarj</a></li>
<li><a href="unpack.html#unbrotli">unbrotli</a></li>
<li><a href="expand.html#uncpio">uncpio</a></li>
<li><a href="unpack.html#undeflate">undeflate</a></li>
<li><a href="unpack.html#undeflate64">undeflate64</a></li>
<li><a href="expand.html#undump">undump</a></li>
<li><a href="unpack.html#unlz4">unlz4</a></li>
<li><a href="unpack.html#unlzma">unlzma</a></li>
<li><a href="unpack.html#unpack200">unpack200</a></li>
<li><a href="unpack.html#unsnappy">unsnappy</a></li>
<li><a href="expand.html#untar">untar</a></li>
<li><a href="unpack.html#unxz">unxz</a></li>
<li><a href="unpack.html#unz">unz</a></li>
<li><a href="expand.html#unzip">unzip</a></li>
<li><a href="unpack.html#unzstd">unzstd</a></li>
<li><a href="pack.html#xz">xz</a></li>
<li><a href="archive.html#zip">zip</a></li>
<li><a href="pack.html#zstd">zstd</a></li>
</ul>
<p>This Antlib contains the following resources:</p>
<ul>
<li><a href="archives.html">archives</a></li>
<li><a href="entry.html#arentry">arentry</a></li>
<li><a href="entry.html#arjentry">arjentry</a></li>
<li><a href="fileset.html#arfileset">arfileset</a></li>
<li><a href="fileset.html#arjfileset">arjfileset</a></li>
<li><a href="compresource.html#brotliresource">brotliresource</a></li>
<li><a href="compresource.html#bzip2resource">bzip2resource</a></li>
<li><a href="entry.html#cpioentry">cpioentry</a></li>
<li><a href="fileset.html#cpiofileset">cpiofileset</a></li>
<li><a href="compresource.html#deflateresource">deflateresource</a></li>
<li><a href="compresource.html#deflate64resource">deflate64resource</a></li>
<li><a href="entry.html#dumpentry">dumpentry</a></li>
<li><a href="fileset.html#dumpfileset">dumpfileset</a></li>
<li><a href="compresource.html#gzipresource">gzipresource</a></li>
<li><a href="compresource.html#lz4resource">lz4resource</a></li>
<li><a href="compresource.html#lzmaresource">lzmaresource</a></li>
<li><a href="compresource.html#pack200resource">pack200resource</a></li>
<li><a href="compresource.html#snappyresource">snappyresource</a></li>
<li><a href="entry.html#tarentry">tarentry</a></li>
<li><a href="fileset.html#sevenzfileset">sevenzfileset</a></li>
<li><a href="entry.html#sevenzentry">sevenzentry</a></li>
<li><a href="fileset.html#tarfileset">tarfileset</a></li>
<li><a href="compresource.html#xzresource">xzresource</a></li>
<li><a href="entry.html#zipentry">zipentry</a></li>
<li><a href="fileset.html#zipfileset">zipfileset</a></li>
<li><a href="compresource.html#zresource">zresource</a></li>
<li><a href="compresource.html#zstdresource">zstdresource</a></li>
</ul>
<p>This Antlib contains the following conditions that work on the
<code>*entry</code>-resources of this Antlib as well as their
counterparts in Ant itself:</p>
<ul>
<li><a href="conditions.html#hasgroupid">hasgroupid</a></li>
<li><a href="conditions.html#hasgroupname">hasgroupname</a></li>
<li><a href="conditions.html#hasmode">hasmode</a></li>
<li><a href="conditions.html#hasuserid">hasuserid</a></li>
<li><a href="conditions.html#hasusername">hasusername</a></li>
</ul>
<h3>Installing and Using</h3>
<p>This Antlib requires Apache Ant 1.8.0 or higher, Apache
Commons Compress 1.16 or higher and Java7 or higher.</p>
<p>In order to use LZMA, XZ or most of the 7z support
the <a href="https://tukaani.org/xz/java.html">XZ for Java</a>
version 1.6 or later is required.</p>
<p>In order to use Brotli
the <a href="https://github.com/google/brotli">Brotli dec</a>
library version 0.1.2 or later is required.</p>
<p>In order to use Zstandard
the <a href="https://github.com/luben/zstd-jni">zstd-jni</a>
library version 1.3.3-1 or later is required.</p>
<p>If you are building the Antlib from sources, run
the <code>antlib</code> target and you'll get a
file <code>ant-compress-VERSION.jar</code>. If you've
downloaded a binary release, you are already there.</p>
<p>In order to use the Antlib, you can either
use <code>taskdef</code> or rely on Ant's autodiscovery by using
an XML namespace and the Antlib's URI. The <code>taskdef</code>
approach allows you to specify a custom classpath while you must
make sure Ant finds the Antlib itself as well as Apache Commons
Compress - either because it is in a well known place like
<code>$ANT_HOME/lib</code> or using the <code>-lib</code>
command line option - when using autodiscovey.</p>
<h4>The <code>taskdef</code> approach</h4>
<p>Before you can use any of the tasks or resources you must use
a <code>taskdef</code> task like:</p>
<pre>
&lt;taskdef
uri="antlib:org.apache.ant.compress"
resource="org/apache/ant/compress/antlib.xml"&gt;
&lt;classpath&gt;
&lt;pathelement location="YOUR-PATH-TO/ant-compress-VERSION1.jar"/&gt;
&lt;pathelement location="YOUR-PATH-TO/commons-compress-VERSION2.jar"/&gt;
&lt;!-- optional dependencies --&gt;
&lt;pathelement location="YOUR-PATH-TO/xz-VERSION3.jar"/&gt;
&lt;pathelement location="YOUR-PATH-TO/dec-VERSION4.jar"/&gt;
&lt;/classpath&gt;
&lt;/taskdef&gt;
</pre>
<p>And later use something like:</p>
<pre>
&lt;comp:tar
xmlns:tar="antlib:org.apache.ant.compress"
...
</pre>
<h4>The autodiscovery approach</h4>
<pre>
&lt;project
xmlns:comp="antlib:org.apache.ant.compress"
...
</pre>
<p>And later use something like:</p>
<pre>
&lt;comp:tar
...
</pre>
</body>
</html>