2001-02-13 12:32:01 +00:00
< html >
< head >
< meta http-equiv = "Content-Language" content = "en-us" >
2002-03-03 06:52:07 +00:00
< title > Zip Task< / title >
2001-02-13 12:32:01 +00:00
< / head >
< body >
< h2 > < a name = "zip" > Zip< / a > < / h2 >
< h3 > Description< / h3 >
< p > Creates a zipfile.< / p >
< p > The < i > basedir< / i > attribute is the reference directory from where to zip.< / p >
< p > Note that file permissions will not be stored in the resulting zipfile.< / p >
< p > It is possible to refine the set of files that are being zipped. This can be
done with the < i > includes< / i > , < i > includesfile< / i > , < i > excludes< / i > , < i > excludesfile< / i > and < i > defaultexcludes< / i >
attributes. With the < i > includes< / i > or < i > includesfile< / i > attribute you specify the files you want to
have included by using patterns. The < i > exclude< / i > or < i > excludesfile< / i > attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the < i > defaultexcludes< / i > attribute, you can specify whether you
want to use default exclusions or not. See the section on < a
href="../dirtasks.html#directorybasedtasks">directory based tasks< / a > , on how the
inclusion/exclusion of files works, and how to write patterns. < / p >
< p > This task forms an implicit < a href = "../CoreTypes/fileset.html" > FileSet< / a > and
supports all attributes of < code > < fileset> < / code >
(< code > dir< / code > becomes < code > basedir< / code > ) as well as the nested
< code > < include> < / code > , < code > < exclude> < / code > and
< code > < patternset> < / code > elements.< / p >
< p > Or, you may place within it nested file sets, or references to file sets.
In this case < code > basedir< / code > is optional; the implicit file set is < i > only used< / i >
if < code > basedir< / code > is set. You may use any mixture of the implicit file set
(with < code > basedir< / code > set, and optional attributes like < code > includes< / code >
and optional subelements like < code > < include> < / code > ); explicit nested
< code > < fileset> < / code > elements so long as at least one fileset total is specified. The ZIP file will
only reflect the relative paths of files < i > within< / i > each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below). < / p >
2002-03-03 06:52:07 +00:00
< p > The Zip task also supports the merging of multiple zip files into the zip file.
This is possible through either the < i > src< / i > attribute of any nested filesets
or by using the special nested fileset < i > zipgroupfileset< / i > .< / p >
2003-02-05 11:20:21 +00:00
< p > The < code > update< / code > parameter controls what happens if the ZIP
file already exists. When set to < code > yes< / code > , the ZIP file is
2001-08-30 13:23:14 +00:00
updated with the files specified. (New files are added; old files are
replaced with the new versions.) When set to < code > no< / code > (the
2003-02-05 11:20:21 +00:00
default) the ZIP file is overwritten. Please note that ZIP files
store file modification times with a granularity of two seconds. If a
file is less than two seconds newer than the entry in the archive, Ant
will not consider it newer.< / p >
2001-02-13 12:32:01 +00:00
< p > The < code > whenempty< / code > parameter controls what happens when no files match.
If < code > skip< / code > (the default), the ZIP is not created and a warning is issued.
If < code > fail< / code > , the ZIP is not created and the build is halted with an error.
If < code > create< / code > , an empty ZIP file (explicitly zero entries) is created,
which should be recognized as such by compliant ZIP manipulation tools.< / p >
2001-07-05 13:10:26 +00:00
< p > This task will now use the platform's default character encoding
for filenames - this is consistent with the command line ZIP tools,
but causes problems if you try to open them from within Java and your
filenames contain non US-ASCII characters. Use the encoding attribute
2001-08-30 13:23:14 +00:00
and set it to UTF8 to create zip files that can safely be read by
2001-07-05 13:10:26 +00:00
Java.< / p >
2002-12-09 12:40:38 +00:00
2003-02-19 07:57:30 +00:00
< p > Starting with Ant 1.5.2, < zip> can store Unix permissions
2002-12-09 12:40:38 +00:00
inside the archive (see description of the filemode and dirmode
2003-04-18 22:02:59 +00:00
attributes for < a href = "../CoreTypes/zipfileset.html" > < zipfileset> < / a > ).
2002-12-09 12:40:38 +00:00
Unfortunately there is no portable way to store these permissions.
Ant uses the algorithm used by < a href = "http://www.info-zip.org" > Info-Zip's< / a >
implementation of the zip and unzip commands - these are the default
versions of zip and unzip for many Unix and Unix-like systems.< / p >
2001-02-13 12:32:01 +00:00
< 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 valign = "top" align = "center" > < b > Required< / b > < / td >
< / tr >
< tr >
2002-01-07 06:22:11 +00:00
< td valign = "top" > destfile< / td >
2001-02-13 12:32:01 +00:00
< td valign = "top" > the zip-file to create.< / td >
2003-04-17 13:09:19 +00:00
< td align = "center" valign = "top" rowspan = "2" > Exactly one of the two.< / td >
2001-02-13 12:32:01 +00:00
< / tr >
2002-06-22 23:38:38 +00:00
< tr >
< td valign = "top" > zipfile< / td >
< td valign = "top" > the < i > deprecated< / i > old name of destfile.< / td >
< / tr >
2001-02-13 12:32:01 +00:00
< tr >
< td valign = "top" > basedir< / td >
< td valign = "top" > the directory from which to zip the files.< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
< tr >
< td valign = "top" > compress< / td >
< td valign = "top" > Not only store data but also compress them, defaults to true< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-07-05 13:10:26 +00:00
< tr >
< td valign = "top" > encoding< / td >
< td valign = "top" > The character encoding to use for filenames
inside the zip file. For a list of possible values see < a
href="http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html">http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html< / a > .
Defaults to the platform's default character encoding.< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-07-12 07:36:50 +00:00
< tr >
< td valign = "top" > filesonly< / td >
< td valign = "top" > Store only file entries, defaults to false< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-02-13 12:32:01 +00:00
< tr >
< td valign = "top" > includes< / td >
2002-06-22 23:38:38 +00:00
< td valign = "top" > comma- or space-separated list of patterns of files that must be
2001-02-13 12:32:01 +00:00
included. All files are included when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > includesfile< / td >
< td valign = "top" > the name of a file. Each line of this file is
taken to be an include pattern< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > excludes< / td >
2002-06-22 23:38:38 +00:00
< td valign = "top" > comma- or space-separated list of patterns of files that must be
2001-02-13 12:32:01 +00:00
excluded. No files (except default excludes) are excluded when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > excludesfile< / td >
< td valign = "top" > the name of a file. Each line of this file is
taken to be an exclude pattern< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > defaultexcludes< / td >
< td valign = "top" > indicates whether default excludes should be used or not
(" yes" /" no" ). Default excludes are used when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
2001-08-30 13:23:14 +00:00
< tr >
< td valign = "top" > update< / td >
< td valign = "top" > indicates whether to update or overwrite
2003-04-11 13:31:18 +00:00
the destination file if it already exists. Default is " false" .< / td >
2001-08-30 13:23:14 +00:00
< td valign = "top" align = "center" > No< / td >
< / tr >
2001-02-13 12:32:01 +00:00
< tr >
< td valign = "top" > whenempty< / td >
2002-03-03 06:52:07 +00:00
< td valign = "top" > behavior when no files match. Valid values are " fail" , " skip" , and " create" . Default is " skip" .< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > duplicate< / td >
< td valign = "top" > behavior when a duplicate file is found. Valid values are " add" , " preserve" , and " fail" . The default value is " add" . < / td >
2001-02-13 12:32:01 +00:00
< td valign = "top" align = "center" > No< / td >
< / tr >
< / table >
< h3 > Parameters specified as nested elements< / h3 >
< h4 > fileset< / h4 >
< p > The zip task supports any number of nested < a
href="../CoreTypes/fileset.html">< code > < fileset> < / code > < / a > elements to specify
the files to be included in the archive.< / p >
2002-12-09 12:40:38 +00:00
2003-04-18 22:02:59 +00:00
< h4 > zipfileset< / h4 >
2002-12-09 12:40:38 +00:00
2003-04-18 22:02:59 +00:00
< p > The zip task supports any number of nested < a
href="../CoreTypes/zipfileset.html">< code > < zipfileset> < / code > < / a > elements to specify
the files to be included in the archive.< / p >
2002-12-09 12:40:38 +00:00
2002-03-03 06:52:07 +00:00
< h4 > zipgroupfileset< / h4 >
< p > A < code > < zipgroupfileset> < / code > allows for multiple zip files to be
merged into the archive. Each file found in this fileset is added to the archive
the same way that < i > zipfileset src< / i > files are added.< / p >
2001-02-13 12:32:01 +00:00
< h3 > Examples< / h3 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip"
2001-02-13 12:32:01 +00:00
basedir=" htdocs/manual"
/> < / 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 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip"
2001-08-30 13:23:14 +00:00
basedir=" htdocs/manual"
update=" true"
/> < / 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 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip"
2001-02-13 12:32:01 +00:00
basedir=" htdocs/manual"
excludes=" mydocs/**, **/todo.html"
/> < / 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 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip"
2001-02-13 12:32:01 +00:00
basedir=" htdocs/manual"
includes=" api/**/*.html"
excludes=" **/todo.html"
/> < / 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 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip" >
2001-02-13 12:32:01 +00:00
< fileset dir=" htdocs/manual" />
< fileset dir=" ." includes=" ChangeLog.txt" />
< /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 >
2002-01-07 06:22:11 +00:00
< pre > < zip destfile=" ${dist}/manual.zip" >
2001-02-13 12:32:01 +00:00
< zipfileset dir=" htdocs/manual" prefix=" docs/user-guide" />
< zipfileset dir=" ." includes=" ChangeLog27.txt" fullpath=" docs/ChangeLog.txt" />
< zipfileset src=" examples.zip" includes=" **/*.html" prefix=" docs/examples" />
< /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 > < code > docs/user-guide/html/index.html
docs/ChangeLog.txt
docs/examples/index.html
< / code > < / pre >
2002-03-03 06:52:07 +00:00
< p >
The code
< pre >
< zip destfile=" ${dist}/manual.zip" >
< zipfileset dir=" htdocs/manual" prefix=" docs/user-guide" />
< zipgroupfileset dir=" ." includes=" examples*.zip" />
< /zip> < / pre >
< / pre >
< p >
< 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 > .
2001-02-13 12:32:01 +00:00
< hr >
2003-02-05 11:20:21 +00:00
< p align = "center" > Copyright © 2000-2003 Apache Software Foundation. All rights
2001-02-13 12:32:01 +00:00
Reserved.< / p >
< / body >
< / html >
