From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:00:02 -0700 Subject: Adding maven and ant source trees Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young --- .../src/ant/apache-ant-1.9.6/manual/Tasks/zip.html | 551 +++++++++++++++++++++ 1 file changed, 551 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html new file mode 100644 index 00000000..4d66851a --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html @@ -0,0 +1,551 @@ + + + + + + +Zip Task + + + + +

Zip

+

Description

+

Creates a zipfile.

+

The basedir attribute is the reference directory from where to zip.

+

Note that file permissions will not be stored in the resulting zipfile.

+

It is possible to refine the set of files that are being zipped. This can be +done with the includes, includesfile, excludes, excludesfile and defaultexcludes +attributes. With the includes or includesfile attribute you specify the files you want to +have included by using patterns. The exclude or excludesfile attribute is used to specify +the files you want to have excluded. This is also done with patterns. And +finally with the defaultexcludes attribute, you can specify whether you +want to use default exclusions or not. See the section on directory based tasks, on how the +inclusion/exclusion of files works, and how to write patterns.

+

This task forms an implicit FileSet and +supports most attributes of <fileset> +(dir becomes basedir) as well as the nested +<include>, <exclude> and +<patternset> elements.

+

Or, you may place within it nested file sets, or references to file sets. +In this case basedir is optional; the implicit file set is only used +if basedir is set. You may use any mixture of the implicit file set +(with basedir set, and optional attributes like includes +and optional subelements like <include>); explicit nested +<fileset> elements so long as at least one fileset total is specified. The ZIP file will +only reflect the relative paths of files within each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes (described below).

+

The Zip task also supports the merging of multiple zip files into the zip file. +This is possible through either the src attribute of any nested filesets +or by using the special nested fileset zipgroupfileset.

+ +

The update parameter controls what happens if the ZIP +file already exists. When set to yes, the ZIP file is +updated with the files specified. (New files are added; old files are +replaced with the new versions.) When set to no (the +default) the ZIP file is overwritten if any of the files that would be +added to the archive are newer than the entries inside the archive. +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, Apache Ant will not consider it newer.

+ +

The whenempty parameter controls what happens when no files match. +If skip (the default), the ZIP is not created and a warning is issued. +If fail, the ZIP is not created and the build is halted with an error. +If create, an empty ZIP file (explicitly zero entries) is created, +which should be recognized as such by compliant ZIP manipulation tools.

+

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 +and set it to UTF8 to create zip files that can safely be read by +Java. For a more complete discussion, +see below

+ +

Starting with Ant 1.5.2, <zip> can store Unix permissions +inside the archive (see description of the filemode and dirmode +attributes for <zipfileset>). +Unfortunately there is no portable way to store these permissions. +Ant uses the algorithm used by Info-Zip's +implementation of the zip and unzip commands - these are the default +versions of zip and unzip for many Unix and Unix-like systems.

+ +

Please note that the zip format allows multiple files of the same +fully-qualified name to exist within a single archive. This has been +documented as causing various problems for unsuspecting users. If you wish +to avoid this behavior you must set the duplicate attribute +to a value other than its default, "add".

+ +

Please also note that different ZIP tools handle timestamps +differently when it comes to applying timezone offset calculations of +files. Some ZIP libraries will store the timestamps as they've been +read from the filesystem while others will modify the timestamps both +when reading and writing the files to make all timestamps use the same +timezone. A ZIP archive created by one library may extract files with +"wrong timestamps" when extracted by another library.

+ +

Ant's ZIP classes use the same algorithm as the InfoZIP tools and +zlib (timestamps get adjusted), Windows' "compressed folders" function +and WinZIP don't change the timestamps. This means that using the +unzip task on files created by Windows' compressed folders function +may create files with timestamps that are "wrong", the same is true if +you use Windows' functions to extract an Ant generated ZIP +archive.

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
destfilethe zip-file to create.Exactly one of the two.
zipfilethe deprecated old name of destfile.
basedirthe directory from which to zip the files.No
compressNot only store data but also compress them, + defaults to true. Unless you set the keepcompression + attribute to false, this will apply to the entire archive, not + only the files you've added while updating.No
keepcompressionFor 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 + compress attribute. Defaults false. Since Ant + 1.6No
encodingThe character encoding to use for filenames + inside the zip file. For a list of possible values see the Supported Encodings.
+ Defaults to the platform's default character encoding. +
See also the discussion below		No
filesonlyStore only file entries, defaults to falseNo
includescomma- or space-separated list of patterns of files that must be + included. All files are included when omitted.No
includesfilethe name of a file. Each line of this file is + taken to be an include patternNo
excludescomma- or space-separated list of patterns of files that must be + excluded. No files (except default excludes) are excluded when omitted.No
excludesfilethe name of a file. Each line of this file is + taken to be an exclude patternNo
defaultexcludesindicates whether default excludes should be used or not + ("yes"/"no"). Default excludes are used when omitted.No
updateindicates whether to update or overwrite + the destination file if it already exists. Default is "false".No
whenemptybehavior when no files match. Valid values are "fail", "skip", and "create". Default is "skip".No
duplicatebehavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". No
roundupWhether the file modification times will be + rounded up to the next even number of seconds.
+ Zip archives store file modification times with a granularity of + two seconds, so the 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. Since Ant 1.6.2		No
commentComment to store in the archive. Since Ant 1.6.3No
levelNon-default level at which file compression should be + performed. Valid values range from 0 (no compression/fastest) to 9 + (maximum compression/slowest). Since Ant 1.7No
preserve0permissionswhen 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.since Ant 1.8.0 + 		No, default is false
useLanguageEncodingFlagWhether 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. + Since Ant 1.8.0. +
See also the discussion below		No, default is true
createUnicodeExtraFieldsWhether 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-encodeable" + which will only add Unicode extra fields if the file name cannot + be encoded using the specified encoding. + Since Ant 1.8.0. +
See also the discussion below		No, default is "never"
fallbacktoUTF8Whether 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. + Since Ant 1.8.0. +
See also the discussion below		No, default is false
zip64ModeWhen to use Zip64 extensions for entries. The + possible values are "never", "always" and "as-needed". + Since Ant 1.9.1. +
See also the discussion below		No, default is "as-needed"
+ +

Encoding of File Names

+ +

Traditionally the ZIP archive format uses CodePage 437 as encoding + for file name, which is not sufficient for many international + character sets.

+ +

Over time different archivers have chosen different ways to work + around the limitation - the java.util.zip packages + simply uses UTF-8 as its encoding for example.

+ +

Ant has been offering the encoding attribute of the zip and unzip + task as a way to explicitly specify the encoding to use (or expect) + since Ant 1.4. It defaults to the platform's default encoding for + zip and UTF-8 for jar and other jar-like tasks (war, ear, ...) as + well as the unzip family of tasks.

+ +

More recent versions of the ZIP specification introduce something + called the "language encoding flag" which can be used to + signal that a file name has been encoded using UTF-8. Starting with + Ant 1.8.0 all zip-/jar- and similar archives written by Ant will set + this flag, if the encoding has been set to UTF-8. Our + interoperabilty tests with existing archivers didn't show any ill + effects (in fact, most archivers ignore the flag to date), but you + can turn off the "language encoding flag" by setting the attribute + useLanguageEncodingFlag to false on the + zip-task if you should encounter problems.

+ +

The unzip (and similar tasks) -task will recognize the language + encoding flag and ignore the encoding set on the task if it has been + found.

+ +

The InfoZIP developers have introduced new ZIP extra fields that + can be used to add an additional UTF-8 encoded file name to the + entry's metadata. Most archivers ignore these extra fields. The + zip family of tasks support an + option createUnicodeExtraFields since Ant 1.8.0 which + makes Ant write these extra fields either for all entries ("always") + or only those whose name cannot be encoded using the specified + encoding (not-encodeable), it defaults to "never" since the extra + fields create bigger archives.

+ +

The fallbackToUTF8 attribute of zip can be used to create archives + that use the specified encoding in the majority of cases but UTF-8 and + the language encoding flag for filenames that cannot be encoded + using the specified encoding.

+ +

The unzip-task will recognize the unicode extra fields by default + and read the file name information from them, unless you set the + optional attribute scanForUnicodeExtraFields to + false.

+ +

Recommendations for Interoperability

+ +

The optimal setting of flags depends on the archivers you expect as + consumers/producers of the ZIP archives. Below are some test + results which may be superseeded with later versions of each + tool.

+ + + +

So, what to do?

+ +

If you are creating jars, then java.util.zip is your main + consumer. We recommend you set the encoding to UTF-8 and keep the + language encoding flag enabled. The flag won't help or hurt + java.util.zip prior to Java7 but archivers that support it will show + the correct file names.

+ +

For maximum interop it is probably best to set the encoding to + UTF-8, enable the language encoding flag and create unicode extra + fields when writing ZIPs. Such archives should be extracted + correctly by java.util.zip, 7Zip, WinZIP, PKWARE tools and most + likely InfoZIP tools. They will be unusable with Windows' + "compressed folders" feature and bigger than archives without the + unicode extra fields, though.

+ +

If Windows' "compressed folders" is your primary consumer, then + your best option is to explicitly set the encoding to the target + platform. You may want to enable creation of unicode extra fields + so the tools that support them will extract the file names + correctly.

+ +

Zip64 extensions

+ +

Zip64 extensions provide a way to create archives bigger than 4GB + or holding more than 65535 entries - or add individual entries + bigger than 4GB using the ZIP extension field mechanism. These + extensions are supported by most modern ZIP implementations.

+ +

When Ant writes compressed entries into the archive it creates it + doesn't know the compressed size of an entry before it has been + written. Unfortunately the decision whether a Zip64 extra field + will be written has to be made before writing the entry's + content.

+ +

Starting with Ant 1.9.0 Ant supports Zip64 extensions but didn't + provide any control over their usage, starting with Ant 1.9.1 a + new zip64mode attribute was added to the zip + family of tasks. It supports three values: + +

+ +

as-needed provides a good compromise if you don't know + whether you archive will exceed the limits of traditional zip files + but don't want to waste too much space (the Zip64 extensions take up + extra space). Unfortunately some ZIP implementations don't + understand Zip64 extra fields or fail to parse archives with extra + fields in local file headers that are not present in the central + directory, one such implementation is the java.util.zip package of + Java5, that's why the jar tasks default + to never. Archives created with as-needed can be + read without problems with Java6 and later.

+ +

Parameters specified as nested elements

+ +

any resource collection

+

Resource +Collections are used to select groups of files to archive.

+

Prior to Ant 1.7 only <fileset> and +<zipfileset> have been supported as nested elements.

+ + +

zipgroupfileset

+

A <zipgroupfileset> 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 zipfileset src files are added.

+ +

<zipgroupfileset> is + a fileset and supports all + of its attributes and nested elements. + +

Examples

+
  <zip destfile="${dist}/manual.zip"
+       basedir="htdocs/manual"
+  />
+

zips all files in the htdocs/manual directory into a file called manual.zip +in the ${dist} directory.

+
  <zip destfile="${dist}/manual.zip"
+       basedir="htdocs/manual"
+       update="true"
+  />
+

zips all files in the htdocs/manual directory into a file called manual.zip +in the ${dist} directory. If manual.zip +doesn't exist, it is created; otherwise it is updated with the +new/changed files.

+
  <zip destfile="${dist}/manual.zip"
+       basedir="htdocs/manual"
+       excludes="mydocs/**, **/todo.html"
+  />
+

zips all files in the htdocs/manual directory. Files in the directory mydocs, +or files with the name todo.html are excluded.

+
  <zip destfile="${dist}/manual.zip"
+       basedir="htdocs/manual"
+       includes="api/**/*.html"
+       excludes="**/todo.html"
+  />
+

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.

+
  <zip destfile="${dist}/manual.zip">
+    <fileset dir="htdocs/manual"/>
+    <fileset dir="." includes="ChangeLog.txt"/>
+  </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.

+
  <zip destfile="${dist}/manual.zip">
+    <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>
+

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 +

+  <zip destfile="${dist}/manual.zip">
+    <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
+    <zipgroupfileset dir="." includes="examples*.zip"/>
+  </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 matches examples*.zip, such as all files within examples1.zip or examples_for_brian.zip. +The same can be achieved with +

+  <zip destfile="${dist}/manual.zip">
+    <mappedresources>
+      <fileset dir="htdocs/manual"/>
+      <globmapper from="*" to="docs/user-guide/*"/>
+    </mappedresources>
+    <archives>
+      <zips>
+        <fileset dir="." includes="examples*.zip"/>
+      </zips>
+    </archives>
+  </zip>
+
+ +The next example + +
+<zip destfile="release.zip">
+  <tarfileset src="release.tar"/>
+</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.

+ + + + + + -- cgit 1.2.3-korg