blob: 285dc46c7cfc8c018cb15b77417ebd1770cdbb7a [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
https://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>Compressing Tasks</title>
</head>
<body>
<h2><a name="pack">Compressing Tasks</a></h2>
<h3>Description</h3>
<p>For each of the supported compression formats there is a
correspondig task that compresses a resource. These tasks are not
based on
their <a href="https://ant.apache.org/manual/CoreTasks/pack.html">core
cousin tasks</a> but provide similar functionality.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">the resource to compress.</td>
<td align="center" valign="top" rowspan="2">Yes, or a nested
resource collection or a nested archiving task.</td>
</tr>
<tr>
<td valign="top">srcfile</td>
<td valign="top">the file to compress.</td>
</tr>
<tr>
<td valign="top">dest</td>
<td valign="top">the destination resource to create.</td>
<td align="center" valign="top" rowspan="2">Exactly one of the
two or a nested dest element.</td>
</tr>
<tr>
<td valign="top">destfile</td>
<td valign="top">the destination file to create.</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>any <a href="https://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
or single element resource collection</h4>
<p>The specified resource will be used as src.</p>
<h4>any <a href="archive.html">archiving task</a></h4>
<p>The task's output will be used as src.</p>
<p>You must not specify the archiving task's dest attribute or
nested element.</p>
<h4>any <a href="#pack">compressing task</a></h4>
<p><em>Since Compress Antlib 1.1</em>
<p>The task's output will be used as src.</p>
<p>You must not specify the compressing task's dest attribute or
nested element.</p>
<h4>dest</h4>
<p>Accepts
any <a href="https://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
or single element resource collection as nested element.</p>
<p>The specified resource will be used as dest.</p>
<h3><a name="bzip2">BZip2</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the BZIP2
compression algorithm.</p>
<h3><a name="deflate">Deflate</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the DEFLATE
compression algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<p>This task supports the following additional attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">level</td>
<td valign="top">Non-default level at which file compression
should be performed. Valid values range from 0 (no
compression/fastest) to 9 (maximum
compression/slowest).</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">zlibheader</td>
<td valign="top">Whether to write ZLIB headers.</td>
<td valign="top" align="center">No, defaults to <code>true</code></td>
</tr>
</table>
<h3><a name="gzip">GZip</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the GZIP
compression algorithm.</p>
<p>This task supports the following additional attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">level</td>
<td valign="top">Non-default level at which file compression
should be performed. Valid values range from 0 (no
compression/fastest) to 9 (maximum
compression/slowest). <em>Since Compress Antlib 1.5</em></td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3><a name="lz4">LZ4</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses
the <a href="https://lz4.github.io/lz4/">LZ4</a> compression
algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<h4>Parameters</h4>
<p>In addition to the attributes supported by all compressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">framed</td>
<td valign="top">Whether to use
the <a href="https://lz4.github.io/lz4/lz4_Frame_format.html">frame
format</a>.
</td>
<td align="center" valign="top">No, defaults to true.</td>
</tr>
</table>
<h3><a name="lzma">LZMA</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the LZMA
compression algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<h3><a name="pack200">Pack200</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses
the <a href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/jar/Pack200.html">Pack200</a>
compression algorithm.</p>
<p>The source of this task must be a valid JAR archive.</p>
<p>The created archive will not be compressed, use
another <code>&lt;gzip&gt;</code> task to create
a <code>pack.gz</code> archive.</p>
<h4>Parameters</h4>
<p>In addition to the attributes supported by all compressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">pack200strategy</td>
<td valign="top">Apache Commons Compress' Pack200 streams cache
the archive data either in memory or in a temporary file.
User this attribute to control which strategy is chosen.
Valid values are "in-memory" and "temp-file".</td>
<td align="center" valign="top">No, defaults to in-memory.</td>
</tr>
</table>
<h4>Parameters specified as nested elements</h4>
<p>In addition to the nested elements supported by all compressing task
this task also supports.</p>
<h5>property</h5>
<p>Sets a property for the packer (see the Pack200 javadocs for
details).</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">key</td>
<td valign="top">Name of the property.</td>
<td align="center" valign="top">Yes.</td>
</tr>
<tr>
<td valign="top">value</td>
<td valign="top">Value of the property.</td>
<td align="center" valign="top">Yes.</td>
</tr>
</table>
<h3><a name="snappy">Snappy</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses
the <a href="https://github.com/google/snappy">Snappy</a>
compression algorithm.</p>
<p><em>Since Compress Antlib 1.5</em>
<h4>Parameters</h4>
<p>In addition to the attributes supported by all compressing task
this task also supports.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">framed</td>
<td valign="top">Whether to use
the <a href="https://github.com/google/snappy/blob/master/framing_format.txt">framing
format</a>.<br/> When setting this to false only resources of
known (uncompressed) size can be compressed (for example
files).
</td>
<td align="center" valign="top">No, defaults to true.</td>
</tr>
</table>
<h3><a name="xz">XZ</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the XZ
compression algorithm.</p>
<h3><a name="zstd">zstd</a></h3>
<p>Is a <a href="#pack">compressing task</a> that uses the Zstandard
compression algorithm.</p>
<p><em>Since Compress Antlib 1.6</em>
<h3>Examples</h3>
<pre>
&lt;cmp:gzip src=&quot;test.tar&quot; dest=&quot;test.tar.gz&quot;
xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre>
<pre>
&lt;cmp:bzip2 src=&quot;test.tar&quot; destfile=&quot;test.tar.bz2&quot;
xmlns:cmp="antlib:org.apache.ant.compress"/&gt;
</pre>
<pre>
&lt;cmp:gzip destfile=&quot;archive.tar.gz&quot; xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;url url="http://example.org/archive.tar"/&gt;
&lt;/cmp:gzip&gt;
</pre>
<p>downloads <i>http://example.org/archive.tar</i> and compresses it
to <i>archive.tar.gz</i> in the project's basedir on the fly.</p>
<pre>
&lt;cmp:gzip xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;cmp:tar&gt;
&lt;fileset dir="src"/&gt;
&lt;/cmp:tar&gt;
&lt;dest&gt;
&lt;file file=&quot;src.tar.gz&quot;/&gt;
&lt;/dest&gt;
&lt;/cmp:gzip&gt;
</pre>
<p>Creates a tar archive of all files in the <i>src</i> directory,
compresses it using GZIP and stores it in the
file <i>src.tar.gz</i> in the project's basedir.</p>
<pre>
&lt;cmp:pack200 dest="foo.pack"
xmlns:cmp="antlib:org.apache.ant.compress"
src="foo.jar"&gt;
&lt;property key="pack.effort" value="9"/&gt;
&lt;/cmp:pack200&gt;
</pre>
<p>Packs <i>foo.jar</i> trying to prepare for better compression
results by using above than normal effort.</p>
<pre>
&lt;cmp:gzip xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;cmp:pack200&gt;
&lt;file file=&quot;foo.jar&quot;/&gt;
&lt;/cmp:pack200&gt;
&lt;dest&gt;
&lt;file file=&quot;foo.pack.gz&quot;/&gt;
&lt;/dest&gt;
&lt;/cmp:gzip&gt;
</pre>
<p>Creates a deflated Pack200 archive of <i>foo.jar</i>and stores it
in the file <i>foo.pack.gz</i> in the project's basedir.</p>
</body>
</html>