From b9421dc80af485591a9c50cc8921f912e0def11e Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:05:40 -0700 Subject: Removing sources to replace with download links instead. Change-Id: Ie28789a725051aec0d1b04dd291b7690a7898668 Signed-off-by: Ashlee Young --- .../src/ant/apache-ant-1.9.6/manual/Tasks/zip.html | 551 --------------------- 1 file changed, 551 deletions(-) delete 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 deleted file mode 100644 index 4d66851a..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/zip.html +++ /dev/null @@ -1,551 +0,0 @@ - - - - - - -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