From 5588e0e665cf2b02a6598d3c68994d9f27ed479f Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Sun, 31 Mar 2013 11:24:47 +0000 Subject: [PATCH] Add documentation for zip64mode attribute git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@1462931 13f79535-47bb-0310-9956-ffa450edef68 --- WHATSNEW | 6 +++++ manual/Tasks/ear.html | 9 ++++++++ manual/Tasks/jar.html | 9 ++++++++ manual/Tasks/war.html | 9 ++++++++ manual/Tasks/zip.html | 52 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 85 insertions(+) diff --git a/WHATSNEW b/WHATSNEW index 164b87013..0803f5350 100644 --- a/WHATSNEW +++ b/WHATSNEW @@ -13,6 +13,12 @@ Fixed bugs: * Corrected XSLTC error in . Bugzilla Report 54641. + * Provide more control over Zip64 extensions created by and + related tasks. In particular no Zip64 extensions will be used at + all by the task family by default - this is required for jars + to be readably by Java5. + Bugzilla Report 54762. + Other changes: -------------- diff --git a/manual/Tasks/ear.html b/manual/Tasks/ear.html index 0138317d6..8dde7dfd5 100644 --- a/manual/Tasks/ear.html +++ b/manual/Tasks/ear.html @@ -264,6 +264,15 @@ to a value other than its default, "add".

Since Ant 1.8.0. No, default is false + + zip64Mode + When to use Zip64 extensions for entries. The + possible values are "never", "always" and "as-needed". + Since Ant 1.9.1. +
See also the discussion in the + zip task page + No, default is "never" +

Nested elements

diff --git a/manual/Tasks/jar.html b/manual/Tasks/jar.html index 1d20d140d..83b2fd0fa 100644 --- a/manual/Tasks/jar.html +++ b/manual/Tasks/jar.html @@ -320,6 +320,15 @@ to a value other than its default, "add".

Since Ant 1.8.0. No, default is false + + zip64Mode + When to use Zip64 extensions for entries. The + possible values are "never", "always" and "as-needed". + Since Ant 1.9.1. +
See also the discussion in the + zip task page + No, default is "never" +

Nested elements

diff --git a/manual/Tasks/war.html b/manual/Tasks/war.html index a84742e09..2c920068e 100644 --- a/manual/Tasks/war.html +++ b/manual/Tasks/war.html @@ -267,6 +267,15 @@ to a value other than its default, "add".

Since Ant 1.8.0. No, default is false + + zip64Mode + When to use Zip64 extensions for entries. The + possible values are "never", "always" and "as-needed". + Since Ant 1.9.1. +
See also the discussion in the + zip task page + No, default is "never" +

Nested elements

diff --git a/manual/Tasks/zip.html b/manual/Tasks/zip.html index 395f97bd7..75d9e2ca4 100644 --- a/manual/Tasks/zip.html +++ b/manual/Tasks/zip.html @@ -272,6 +272,14 @@ archive.


See also the discussion below No, default is false + + zip64Mode + When 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

@@ -390,6 +398,50 @@ archive.

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: + +

    +
  • never means no Zip64 extra fields will ever be + written, this is the behavior of Ant 1.8.x and earlier and the + default behavior of jar, ear + and war starting with Ant 1.9.1.
    • +
  • always means Zip64 extra fields are written for all + entries.
    • +
  • as-needed means Zip64 extra fields are written for all + compressed entries to the "local file header" (by default these + are all files but not the directories) but only written to the + central directory if the entry really required Zip64 features. + This is the default behavior of Ant 1.9.0 and remains the default + behavior of the zip task.
    • +
+ +

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