Zip

説明

zipファイルを作成します。

basedir属性は、zip化する際の基準ディレクトリです。

ファイルパーミッションは、結果として作成されるzipファイルには保存されないことに注意してください。

zip化されるファイルのセットを絞り込むことができます。これは、includes、includesfile、excludes、excludesfile、およびdefaultexcludes属性を使用して行うことができます。includesまたはincludesfile属性では、パターンを使用して含めるファイルを指定します。excludeまたはexcludesfile属性は、除外するファイルを指定するために使用します。これもパターンで行います。最後に、defaultexcludes属性を使用して、デフォルトの除外を使用するかどうかを指定できます。ファイルの包含/除外の仕組み、およびパターンの記述方法については、ディレクトリベースのタスクのセクションを参照してください。

このタスクは暗黙的なFileSetを形成し、<fileset>のほとんどの属性(dirはbasedirになる)と、ネストされた<include>、<exclude>、<patternset>要素をサポートします。

または、ネストされたファイルセット、またはファイルセットへの参照を配置することもできます。この場合、basedirはオプションです。暗黙的なファイルセットは、basedirが設定されている場合にのみ使用されます。暗黙的なファイルセット(basedirが設定され、includesのようなオプション属性や<include>のようなオプションのサブ要素を含む)、明示的なネストされた<fileset>要素を自由に組み合わせて使用できます。ただし、少なくとも1つのファイルセットを合計で指定する必要があります。ZIPファイルには、各ファイルセット内のファイルの相対パスのみが反映されます。Zipタスクとその派生タスクは、zipfilesetという名前のファイルセットの特別な形式を知っており、追加の属性(以下で説明)を持っています。

Zipタスクは、複数のzipファイルをzipファイルにマージすることもサポートしています。これは、ネストされたファイルセットのsrc属性を使用するか、特別なネストされたファイルセットzipgroupfilesetを使用することで可能です。

updateパラメーターは、ZIPファイルが既に存在する場合の処理を制御します。 yesに設定すると、ZIPファイルは指定されたファイルで更新されます。(新しいファイルが追加され、古いファイルは新しいバージョンに置き換えられます。) no(デフォルト)に設定すると、アーカイブに追加されるファイルがいずれもアーカイブ内のエントリよりも新しい場合に、ZIPファイルが上書きされます。 ZIPファイルはファイル更新時刻を2秒の粒度で保存することに注意してください。ファイルがアーカイブ内のエントリよりも2秒未満だけ新しい場合、Apache Antはそれを新しいとは見なしません。

whenemptyパラメーターは、ファイルが一致しない場合の処理を制御します。 skip(デフォルト)の場合、ZIPは作成されず、警告が出力されます。failの場合、ZIPは作成されず、ビルドがエラーで停止します。createの場合、空のZIPファイル(明示的にエントリがゼロ)が作成されます。これは、準拠したZIP操作ツールでそのように認識されるはずです。

このタスクでは、ファイル名にデフォルトのJVM文字エンコーディングを使用するようになりました。これはコマンドラインZIPツールと一貫性がありますが、ファイル名にUS-ASCII以外の文字が含まれている場合にJava内から開こうとすると問題が発生します。Javaで安全に読み込めるzipファイルを作成するには、encoding属性を使用し、UTF8に設定してください。詳細については、下記を参照してください。

Ant 1.5.2以降、<zip>はアーカイブ内にUnixパーミッションを保存できます(<zipfileset>のfilemode属性とdirmode属性の説明を参照)。残念ながら、これらのパーミッションを保存するポータブルな方法はありません。 Antは、Info-Zipのzipおよびunzipコマンドの実装で使用されるアルゴリズムを使用します。これらは、多くのUnixのようなシステムでのzipおよびunzipのデフォルトバージョンです。

zip形式では、同じ完全修飾名の複数のファイルが1つのアーカイブ内に存在できることに注意してください。これは、不審なユーザーにさまざまな問題を引き起こすことが文書化されています。この動作を回避したい場合は、duplicate属性をデフォルトのadd以外の値に設定する必要があります。

また注意してください、異なるZIPツールは、ファイルのタイムゾーンオフセット計算を適用する際に、タイムスタンプを異なる方法で処理します。一部のZIPライブラリは、ファイルシステムから読み取ったときのタイムスタンプを保存しますが、別のライブラリは、すべてのタイムスタンプが同じタイムゾーンを使用するように、ファイルの読み取り時と書き込み時の両方でタイムスタンプを変更します。あるライブラリで作成されたZIPアーカイブは、別のライブラリで展開されると、「間違ったタイムスタンプ」でファイルを展開する可能性があります。

AntのZIPクラスは、InfoZIPツールとzlib(タイムスタンプが調整される)、Windowsの「圧縮フォルダー」機能、およびWinZIPと同じアルゴリズムを使用します(タイムスタンプは変更されません)。つまり、Windowsの圧縮フォルダー機能で作成されたファイルにunzipタスクを使用すると、タイムスタンプが「間違って」いるファイルが作成される可能性があります。Windowsの機能を使用してAntで生成されたZIPアーカイブを展開する場合も同様です。

パラメーター

ファイル名のエンコーディング

従来、ZIPアーカイブ形式では、ファイル名のエンコーディングとしてCodePage 437を使用していますが、これは多くの国際文字セットには不十分です。

時間の経過とともに、さまざまなアーカイバが制限を回避するためにさまざまな方法を選択してきました。たとえば、java.util.zipパッケージは、エンコーディングとしてUTF-8を使用しています。

Antは、使用する(または期待する)エンコーディングを明示的に指定する方法として、Ant 1.4以降、zipタスクとunzipタスクのencoding属性を提供しています。デフォルトは、zipの場合はデフォルトのJVM文字エンコーディング、jarやその他のjarのようなタスク(war、ear、...)およびunzipファミリのタスクの場合はUTF-8です。

ZIP仕様のより新しいバージョンでは、ファイル名がUTF-8を使用してエンコードされたことを示すために使用できる言語エンコーディングフラグと呼ばれるものが導入されています。Ant 1.8.0以降、Antによって書き込まれるすべてのzip、jar、および同様のアーカイブは、エンコーディングがUTF-8に設定されている場合、このフラグを設定します。既存のアーカイバとの相互運用性テストでは、悪影響は見られませんでした(実際、ほとんどのアーカイバは今日までフラグを無視しています)。ただし、問題が発生した場合は、zipタスクでuseLanguageEncodingFlag属性をfalseに設定することで、言語エンコーディングフラグをオフにすることができます。

unzipタスク(および同様のタスク)は、言語エンコーディングフラグを認識し、見つかった場合はタスクに設定されたエンコーディングを無視します。

InfoZIPの開発者は、エントリのメタデータにUTF-8でエンコードされた追加のファイル名を追加するために使用できる、新しいZIPエクストラフィールドを導入しました。ほとんどのアーカイバはこれらのエクストラフィールドを無視します。Ant 1.8.0以降、zipファミリのタスクは、createUnicodeExtraFieldsオプションをサポートしています。これにより、Antはこれらのエクストラフィールドをすべてのエントリに対して(always)、または指定されたエンコーディングを使用して名前をエンコードできないエントリに対してのみ(not-encodeable)書き込みます。エクストラフィールドによってアーカイブが大きくなるため、デフォルトはneverです。

zipタスクのfallbackToUTF8属性を使用すると、ほとんどの場合に指定されたエンコーディングを使用し、指定されたエンコーディングでエンコードできないファイル名にはUTF-8と言語エンコーディングフラグを使用するアーカイブを作成できます。

unzipタスクは、オプションの属性scanForUnicodeExtraFieldsをfalseに設定しない限り、デフォルトでUnicode拡張フィールドを認識し、そこからファイル名情報を読み取ります。

相互運用性に関する推奨事項

フラグの最適な設定は、ZIPアーカイブのコンシューマー/プロデューサーとして想定するアーカイバーによって異なります。以下は、各ツールの今後のバージョンで置き換えられる可能性のあるテスト結果です。

• jar実行可能ファイルで使用されるか、CLASSPATHからjarを読み取るために使用されるjava.util.zipパッケージは、UTF-8の名前を読み書きしますが、フラグやUnicode拡張フィールドを設定または認識しません。
• Java 7以降、java.util.zipはデフォルトでUTF-8を書き込み、言語エンコーディングフラグを使用します。新しいコンストラクターを介してZIPの読み取り/書き込み時に異なるエンコーディングを指定できます。パッケージは、読み取り時に言語エンコーディングフラグを認識し、Unicode拡張フィールドを無視するようになりました。
• 7ZipはデフォルトでCodePage 437を書き込みますが、CodePage 437としてエンコードできないエントリを書き込む場合は、UTF-8と言語エンコーディングフラグを使用します（fallbacktoUTF8をtrueに設定したzipタスクと同様）。読み取り時に言語エンコーディングフラグを認識し、Unicode拡張フィールドを無視します。
• WinZIPは、デフォルトでCodePage 437を書き込み、Unicode拡張フィールドを使用します。読み取り時にUnicode拡張フィールドと言語エンコーディングフラグを認識します。
• Windowsの「圧縮フォルダー」機能は、フラグや拡張フィールドを認識せず、デフォルトのプラットフォームエンコーディングを使用してアーカイブを作成し、読み取り時にはアーカイブがそのエンコーディングであることを期待します。
• InfoZIPベースのツールは両方を認識して書き込むことができますが、コンパイル時のオプションであり、プラットフォームによって異なるため、結果は異なる場合があります。
• PKWARE zipツールは両方を認識し、言語エンコーディングフラグを優先します。可能であればCodePage 437を使用してアーカイブを作成し、CodePage 437としてエンコードできないファイル名にはUTF-8と言語エンコーディングフラグを使用します。

では、どうすればよいでしょうか？

jarを作成している場合、java.util.zipが主なコンシューマーです。エンコーディングをUTF-8に設定し、言語エンコーディングフラグを有効にしておくことをお勧めします。このフラグは、Java 7より前のjava.util.zipには役立ちも害もありませんが、それをサポートするアーカイバーは正しいファイル名を表示します。

最大限の相互運用性を実現するには、エンコーディングをUTF-8に設定し、言語エンコーディングフラグを有効にして、ZIPを書き込むときにUnicode拡張フィールドを作成するのがおそらく最適です。このようなアーカイブは、java.util.zip、7Zip、WinZIP、PKWAREツール、およびおそらくほとんどのInfoZIPツールによって正しく抽出されるはずです。ただし、Windowsの「圧縮フォルダー」機能では使用できず、Unicode拡張フィールドがないアーカイブよりも大きくなります。

Windowsの「圧縮フォルダー」が主なコンシューマーである場合は、ターゲットプラットフォームにエンコーディングを明示的に設定するのが最善のオプションです。サポートするツールがファイル名を正しく抽出できるように、Unicode拡張フィールドの作成を有効にすることができます。

Zip64拡張

Zip64拡張機能は、4 GBを超えるアーカイブを作成したり、65535を超えるエントリを保持したり、ZIP拡張フィールドメカニズムを使用して4 GBを超える個々のエントリを追加したりする方法を提供します。これらの拡張機能は、ほとんどの最新のZIP実装でサポートされています。

Antが圧縮されたエントリをアーカイブに書き込むとき、書き込まれるまでエントリの圧縮サイズを認識しません。残念ながら、Zip64拡張フィールドを書き込むかどうかを決定する必要があるのは、エントリの内容を書き込む前です。

Ant 1.9.0でZip64拡張のサポートが導入されましたが、その使用に関する制御は提供されませんでした。Ant 1.9.1以降、新しいzip64mode属性がzipタスクファミリに追加されました。これは3つの値をサポートします

• neverは、Zip64拡張フィールドが書き込まれないことを意味します。これは、Ant 1.9.0より前の動作であり、Ant 1.9.1以降のjar、ear、warのデフォルトの動作です。
• alwaysは、すべてのエントリにZip64拡張フィールドが書き込まれることを意味します。
• as-neededは、すべての圧縮されたエントリに対して「ローカルファイルヘッダー」（デフォルトではこれらはすべてのファイルですが、ディレクトリは除きます）にZip64拡張フィールドが書き込まれますが、エントリが本当にZip64機能を必要とする場合にのみ、中央ディレクトリに書き込まれることを意味します。これは、Ant 1.9.0のデフォルトの動作であり、zipタスクのデフォルトの動作のままです。

as-neededは、アーカイブが従来のzipファイルの制限を超えるかどうか不明であるが、スペースを無駄にしたくない場合に適切な妥協案を提供します（Zip64拡張は追加のスペースを必要とします）。残念ながら、一部のZIP実装はZip64拡張フィールドを理解していないか、中央ディレクトリに存在しないローカルファイルヘッダーに拡張フィールドを持つアーカイブの解析に失敗します。そのような実装の1つがJava 5のjava.util.zipパッケージであるため、jarタスクのデフォルトはneverです。as-neededで作成されたアーカイブは、Java 6以降で問題なく読み取ることができます。

ネストされた要素として指定されたパラメーター

任意のリソースコレクション

リソースコレクションは、アーカイブするファイルのグループを選択するために使用されます。

Ant 1.7より前では、<fileset>と<zipfileset>のみがネストされた要素としてサポートされていました。

zipgroupfileset

<zipgroupfileset>を使用すると、複数のzipファイルをアーカイブにマージできます。このfilesetで見つかった各ファイルは、zipfilesetのsrcファイルが追加されるのと同じ方法でアーカイブに追加されます。

<zipgroupfileset>はfilesetであり、そのすべての属性とネストされた要素をサポートします。

例

htdocs/manualディレクトリ内のすべてのファイルを${dist}ディレクトリ内のmanual.zipというファイルにzip圧縮します。

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

htdocs/manualディレクトリ内のすべてのファイルを${dist}ディレクトリ内のmanual.zipというファイルにzip圧縮します。manual.zipが存在しない場合は作成されます。それ以外の場合は、新しい/変更されたファイルで更新されます。

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

htdocs/manualディレクトリ内のすべてのファイルをzip圧縮します。mydocsディレクトリ内のファイル、またはtodo.htmlという名前のファイルは除外されます。

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

htdocs/manualディレクトリ内のすべてのファイルをzip圧縮します。apiディレクトリ下のhtmlファイルのみがzip圧縮され、todo.htmlという名前のファイルは除外されます。

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

htdocs/manualディレクトリ内のすべてのファイルをzip圧縮し、現在のディレクトリにあるファイルChangeLog.txtも追加します。ChangeLog.txtは、htdocs/manual/ChangeLog.txtにあった場合と同じように、ZIPファイルの先頭に追加されます。

<zip destfile="${dist}/manual.zip">
  <fileset dir="htdocs/manual"/>
  <fileset dir="." includes="ChangeLog.txt"/>
</zip>

htdocs/manualディレクトリ内のすべてのファイルをアーカイブのdocs/user-guideディレクトリにzip圧縮し、現在のディレクトリにあるファイルChangeLog27.txtをdocs/ChangeLog.txtとして追加し、examples.zip内のすべてのhtmlファイルをdocs/examplesに追加します。

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

アーカイブには、最終的に次のファイルが含まれる可能性があります

    docs/user-guide/html/index.html
    docs/ChangeLog.txt
    docs/examples/index.html

htdocs/manualディレクトリ内のすべてのファイルをアーカイブのdocs/user-guideディレクトリにzip圧縮し、examples*.zipに一致する任意のファイル内のすべてのファイル（examples1.zipまたはexamples_for_brian.zip内のすべてのファイルなど）を追加します。

<zip destfile="${dist}/manual.zip">
  <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
  <zipgroupfileset dir="." includes="examples*.zip"/>
</zip>

同じことを以下で実現できます

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

TARアーカイブをZIPアーカイブとして再パッケージ化します。Unixファイル権限がTARファイルの一部として保存されている場合は、結果のZIPアーカイブに保持されます。

<zip destfile="release.zip">
  <tarfileset src="release.tar"/>
</zip>