You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by bo...@apache.org on 2009/09/10 13:48:17 UTC
svn commit: r813385 - in /ant/sandbox/antlibs/compress/trunk/docs:
archive.html expand.html pack.html
Author: bodewig
Date: Thu Sep 10 11:48:16 2009
New Revision: 813385
URL: http://svn.apache.org/viewvc?rev=813385&view=rev
Log:
add documentation for archiving tasks, fix some errors in the pack and expand manuals
Added:
ant/sandbox/antlibs/compress/trunk/docs/archive.html (with props)
Modified:
ant/sandbox/antlibs/compress/trunk/docs/expand.html
ant/sandbox/antlibs/compress/trunk/docs/pack.html
Added: ant/sandbox/antlibs/compress/trunk/docs/archive.html
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/compress/trunk/docs/archive.html?rev=813385&view=auto
==============================================================================
--- ant/sandbox/antlibs/compress/trunk/docs/archive.html (added)
+++ ant/sandbox/antlibs/compress/trunk/docs/archive.html Thu Sep 10 11:48:16 2009
@@ -0,0 +1,482 @@
+<!--
+ 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>Archiving Task</title>
+</head>
+
+<body>
+
+ <h2><a name="archive">Archiving Tasks</a></h2>
+
+ <p>For each of the supported archiving formats there is a
+ correspondig <code>archiving</code> task. These tasks are
+ supersets of the
+ core <a href="http://ant.apache.org/manual/CoreTasks/tar.html">tar</a>
+ and <a href="http://ant.apache.org/manual/CoreTasks/zip.html">zip</a>
+ 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 <a href="#tar">tar</a> and <a href="#zip">zip</a>
+ documentation for details.</p>
+
+ <p>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 <a href="entry.html"><code>entry</code></a> or
+ <a href="fileset.html"><code>fileset</code></a> resources or are
+ core <a href="http://ant.apache.org/manual/CoreTypes/resources.html#tarentry"><code>tarentry</code></a>
+ or <a href="http://ant.apache.org/manual/CoreTypes/resources.html#zipentry"><code>zipentry</code></a>
+ resources or returned by a
+ core <a href="http://ant.apache.org/manual/CoreTypes/tarfileset.html"><code>tarfileset</code></a>
+ or <a href="http://ant.apache.org/manual/CoreTypes/zipfileset.html"><code>zipfileset</code></a>
+ - the task will try to preserve the entry's permissions and as
+ many other attributes of the entry as the archiving format
+ supports.</p>
+
+ <p>All archiving tasks share the following attributes and nested
+ elements:</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">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>
+ <tr>
+ <td valign="top">encoding</td>
+ <td valign="top">The character encoding to use for filenames
+ inside the archive. For a list of possible values
+ see <a href="http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html">http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html</a>.
+ The magic value
+ <code>native-encoding</code> can be used to explicitly select
+ the platform's default character encoding. Defaults to the
+ platform's default character encoding.<br/>
+ Currently ignored by all but the zip task.
+ </td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">filesonly</td>
+ <td valign="top">Store only file entries, defaults to true</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">preserve0permissions</td>
+ <td valign="top">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.<br/>
+ Set this attribute to true if you really want to preserve the
+ original permission field.
+ Default is false.
+ </td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">roundup</td>
+ <td valign="top">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.<br/>
+
+ 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.<br/>
+
+ Defaults to true.
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">preserveLeadingSlashes</td>
+ <td valign="top">Indicates whether leading `/'s should
+ be preserved in the file names. Default is <code>false</code>.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">duplicate</td>
+ <td valign="top">behavior when a duplicate entry is found.
+ Valid values are "add", "preserve", and
+ "fail". The default value is
+ "fail". </td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">whenempty</td>
+ <td valign="top">behavior when no files match. Valid values are
+ "fail" and "skip". Default is
+ "fail".</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ </table>
+
+ <h3>Parameters specified as nested elements</h3>
+
+ <h4>dest</h4>
+
+ <p>Accepts
+ any <a href="http://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>
+
+ <h4>any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
+ or resource collection</h4>
+
+ <p>This specifies the files and directories that shall be added to
+ the archive.</p>
+
+ <h3><a name="ar">Ar</a></h3>
+
+ <p>An <a href="#archive">archiving task</a> creating archives of the
+ AR format.</p>
+
+ <p>The AR format is pretty limited, it can only store file names up
+ to 16 characters and not store directories at all. It is not
+ possible to set the <code>filesonly</code> attribute to true for
+ the <code>ar</code> task.</p>
+
+ <h3><a name="cpio">Cpio</a></h3>
+
+ <p>An <a href="#archive">archiving task</a> creating archives of the
+ CPIO format.</p>
+
+ <h3><a name="tar">Tar</a></h3>
+
+ <p>An <a href="#archive">archiving task</a> creating archives of the
+ TAR format.</p>
+
+ <p>This task does not support the <code>compression</code> attribute
+ of
+ the <a href="http://ant.apache.org/manual/CoreTasks/tar.html">core
+ task</a>. You should use a <a href="pack.html">compressing
+ task</a> with a <code>tar</code> task as nested element
+ instead.</p>
+
+ <h4>Examples</h4>
+
+<pre>
+<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"/></pre>
+
+ <p>tars all files in the <code>htdocs/manual</code> directory into a
+ file called <code>manual.tar</code> in the <code>${dist}</code>
+ directory, then applies the gzip task to compress it.</p>
+
+<pre>
+<cmp:tar destfile="${dist}/manual.tar"
+ xmlns:cmp="antlib:org.apache.ant.compress">
+ <fileset dir="htdocs/manual"
+ excludes="mydocs/**, **/todo.html"
+ />
+<cmp:tar/></pre>
+
+ <p>tars all files in the <code>htdocs/manual</code> directory into a
+ file called <code>manual.tar</code> in the <code>${dist}</code>
+ directory. Files in the directory <code>mydocs</code>, or files
+ with the name <code>todo.html</code> are excluded.</p>
+
+<pre>
+<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></pre>
+
+ <p>Writes the file <code>docs/readme.txt</code> as
+ <code>/usr/doc/ant/README</code> into the archive. All
+ <code>*.html</code> files in the <code>docs</code> directory are
+ prefixed by <code>/usr/doc/ant</code>, so for example
+ <code>docs/index.html</code> is written as
+ <code>/usr/doc/ant/index.html</code> to the archive.</p>
+
+<!--pre>
+<tar longfile="gnu"
+ 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>
+</tar>
+</pre>
+<p>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. </p-->
+
+<pre>
+<cmp:gzip destfile="release.tar.gz" xmlns:cmp="antlib:org.apache.ant.compress">
+ <cmp:tar>
+ <cmp:zipfileset src="release.zip"/>
+ </cmp:tar>
+</cmp:gzip>
+</pre>
+
+ <p>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.</p>
+
+ <h3><a name="zip">Zip</a></h3>
+
+ <p>An <a href="#archive">archiving task</a> creating archives of the
+ ZIP format.</p>
+
+ <p>The discussion about encodings in
+ the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">core
+ zip task manual</a> applies to this task as well.</p>
+
+ <p><b>Note</b> the following attributes have default values
+ different from the core zip
+ task: <code>filesonly</code>, <code>whenempty</code>
+ and <code>duplicate</code>. The core task's <code>compress</code>
+ attribute isn't available for this task, use
+ the <code>level</code> attribute instead where a level of 0
+ corresponds to no compression and not specifying a level at all to
+ default compression.</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).</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">comment</td>
+ <td valign="top">Comment to store in the archive.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">keepcompression</td>
+ <td valign="top">For entries coming from existing archives (like
+ nested <em>zipfileset</em>s or while updating the archive), keep
+ the compression as it has been originally instead of using the
+ <em>level</em> attribute. Defaults false.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">useLanguageEncodingFlag</td>
+ <td valign="top">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.
+ <br/>See also
+ the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
+ in the core task's manual.
+ Default is true.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">createUnicodeExtraFields</td>
+ <td valign="top">Whether to create unicode extra fields to store
+ the file names a second time inside the entry's metadata.
+ <br>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.
+ <br/>See also
+ the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
+ in the core task's manual.
+ Default is "never".</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">fallbacktoUTF8</td>
+ <td valign="top">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.
+ <br/>See also
+ the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
+ in the core task's manual.
+ Default is false.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ </table>
+
+<h3>Examples</h3>
+<pre>
+<cmp:zip destfile="${dist}/manual.zip
+ xmlns:cmp="antlib:org.apache.ant.compress"">
+ <fileset dir="htdocs/manual"/>
+<cmp:zip/>
+</pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory into a
+ file called <code>manual.zip</code> in the <code>${dist}</code>
+ directory.</p>
+
+<!--pre>
+<cmp:zip destfile="${dist}/manual.zip"
+ mode="update"
+ xmlns:cmp="antlib:org.apache.ant.compress"">
+ <fileset dir="htdocs/manual"/>
+</cmp:zip></pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory into a
+ file called <code>manual.zip</code> in the <code>${dist}</code>
+ directory. If <code>manual.zip</code> doesn't exist, it is
+ created; otherwise it is updated with the new/changed files.</p-->
+
+<pre>
+<cmp:zip destfile="${dist}/manual.zip"
+ xmlns:cmp="antlib:org.apache.ant.compress"">
+ <fileset dir="htdocs/manual"
+ excludes="mydocs/**, **/todo.html"
+ />
+</cmp:zip>
+</pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory. Files
+ in the directory <code>mydocs</code>, or files with the
+ name <code>todo.html</code> are excluded.</p>
+
+<pre>
+<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>
+</pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory. Only
+ html files under the directory <code>api</code> are zipped, and
+ files with the name <code>todo.html</code> are excluded.</p>
+
+<pre>
+<cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
+ <fileset dir="htdocs/manual"/>
+ <fileset dir="." includes="ChangeLog.txt"/>
+</cmp:zip></pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory, and
+ also adds the file <code>ChangeLog.txt</code> in the current
+ directory. <code>ChangeLog.txt</code> will be added to the top of
+ the ZIP file, just as if it had been located
+ at <code>htdocs/manual/ChangeLog.txt</code>.</p>
+
+<pre>
+<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></pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory into
+ the <code>docs/user-guide</code> directory in the archive, adds
+ the file <code>ChangeLog27.txt</code> in the current directory
+ as <code>docs/ChangeLog.txt</code>, and includes all the html
+ files in <code>examples.zip</code>
+ under <code>docs/examples</code>. The archive might end up
+ containing the files:</p>
+<pre> docs/user-guide/html/index.html
+ docs/ChangeLog.txt
+ docs/examples/index.html
+</pre>
+
+ <p>The code</p>
+
+<pre>
+<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>
+</pre>
+
+ <p>zips all files in the <code>htdocs/manual</code> directory into
+ the <code>docs/user-guide</code> directory in the archive and
+ includes all the files in any file that
+ maches <code>examples*.zip</code>, such as all files
+ within <code>examples1.zip</code>
+ or <code>examples_for_brian.zip</code>. The same can be achieved
+ with</p>
+
+<pre>
+<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>
+</pre>
+
+ <p>The next example</p>
+
+<pre>
+<cmp:zip dest="release.zip" xmlns:cmp="antlib:org.apache.ant.compress"">
+ <cmp:tarfileset src="release.tar"/>
+</cmp:zip>
+</pre>
+
+ <p>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.</p>
+
+</body>
+</html>
Propchange: ant/sandbox/antlibs/compress/trunk/docs/archive.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified: ant/sandbox/antlibs/compress/trunk/docs/expand.html
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/compress/trunk/docs/expand.html?rev=813385&r1=813384&r2=813385&view=diff
==============================================================================
--- ant/sandbox/antlibs/compress/trunk/docs/expand.html (original)
+++ ant/sandbox/antlibs/compress/trunk/docs/expand.html Thu Sep 10 11:48:16 2009
@@ -135,25 +135,23 @@
</tr>
<tr>
<td valign="top">encoding</td>
- <td valign="top"><b>Note:</b> This attribute is not available for
- the <code>untar</code> task.<br>
+ <td valign="top">
The character encoding that has been used for filenames
inside the zip file. For a list of possible values see <a
href="http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html">http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html</a>.<br>
Defaults to "UTF8", use the magic value
<code>native-encoding</code> for the platform's default character
encoding.
- <br/>See also the <a href="zip.html#encoding">discussion in the
+ <br/>See also the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion in the
zip task page</a></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">scanForUnicodeExtraFields</td>
- <td valign="top"><b>Note:</b> This attribute is not available for
- the <code>untar</code> task.<br>
+ <td valign="top">
If the archive contains uncode extra fields then use them to set
the file names, ignoring the specified encoding.
- <br/>See also the <a href="zip.html#encoding">discussion in the
+ <br/>See also the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion in the
zip task page</a></td>
<td align="center" valign="top">No, defaults to true</td>
</tr>
Modified: ant/sandbox/antlibs/compress/trunk/docs/pack.html
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/compress/trunk/docs/pack.html?rev=813385&r1=813384&r2=813385&view=diff
==============================================================================
--- ant/sandbox/antlibs/compress/trunk/docs/pack.html (original)
+++ ant/sandbox/antlibs/compress/trunk/docs/pack.html Thu Sep 10 11:48:16 2009
@@ -53,7 +53,8 @@
<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.</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>
@@ -61,6 +62,8 @@
</tr>
</table>
+ <h3>Parameters specified as nested elements</h3>
+
<h4>any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
or single element resource collection</h4>