document <archives>. PR 46257.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@721525 13f79535-47bb-0310-9956-ffa450edef68
16 years ago · 6eb8c15ed0
--- a/+ 6
+++ b/+ 6
@@ -575,6 +575,12 @@ Other changes:
   processing in Xerces, for example.
   Bugzilla Report 36653.

 * a new resource collection <archives> can be used to specify
   collections of ZIP and TAR archives as source and extracts them on
   the fly.  This is a generalization of the <zipgroupfileset> found
   as nested element of <zip> and friends.
   Bugzilla Report 46257.

 Changes from Ant 1.7.0 TO Ant 1.7.1
 =============================================

--- a/docs/manual/CoreTasks/zip.html
+++ b/docs/manual/CoreTasks/zip.html
@@ -314,6 +314,22 @@ The code
 </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>.
 The same can be achieved with
 <pre>
  &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
    &lt;mappedresources&gt;
      &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
      &lt;globmapper from="*" to="docs/user-guide/*"/&gt;
    &lt;/mappedresources&gt;
    &lt;archives&gt;
      &lt;zips&gt;
        &lt;fileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
      &lt;/zips&gt;
    &lt;/archives&gt;
  &lt;/zip&gt;
 </pre>

 The next example

 <pre>
 &lt;zip dest="release.zip"&gt;
@@ -321,7 +337,7 @@ The code
 &lt;/zip&gt;
 </pre>

 <p>Re-packages a TAR archive as a ZIP archive.  If Unix file
 <p>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.</p>

--- a/docs/manual/CoreTypes/resources.html
+++ b/docs/manual/CoreTypes/resources.html
@@ -349,6 +349,9 @@ Ant's "legacy" datatypes have been modified to behave as Resource Collections:
  <li><a href="#mappedresources">mappedresources</a> - generic
    resource collection wrapper that maps the names of the nested
    resources using a <a href="mapper.html">mapper</a>.</li>
  <li><a href="#archives">archives</a> - wraps around different
    resource collections and treats the nested resources as ZIP or TAR
    archives that will be extracted on the fly.</li>
 </ul>
 <h4><a name="resources">resources</a></h4>
 <p>A generic resource collection, designed for use with
@@ -1075,5 +1078,50 @@ larger collection. <strong>Since Ant 1.7.1</strong>.</p>
  </pre>    
 </blockquote>

 <h4><a name="archives">archives</a></h4>

 <p>This resource collection accepts an arbitrary number of nested
  resources and assumes that all those resources must be either ZIP or
  TAR archives.  The resources returned
  by <code>&lt;archives&gt;</code> are the contents of the nested
  archives.</p>

 <p>This resource collection is a generalization
  of <a href="../CoreTasks/zip.html#zipgroupfileset">zipgroupfileset</a>
  which is only supported by the zip family of tasks.</p>

 <p><em>archives</em> doesn't support any attributes.</p>

 <blockquote>
  <h4>Parameters specified as nested elements</h4>

  <p><code>&lt;archives&gt;</code> has two nested
    elements <code>&lt;zips&gt;</code> and
    <code>&ls;tars&gt;</code> that are <a href="#union">unions</a>
    themselves, i.e. they accept arbitrary many resource(collection)s
    as nested elements.</p>

  <p>The nested resources of &lt;zips&gt; are treated as ZIP archives,
    the nested resources of &lt;tars&gt; as TAR archives.</p>

  <h4>Examples</h4>

  <p>Copies all files from all jars that are on the classpath
    to <code>${target}</code>.</p>

  <pre>
    &lt;copy todir="${target}"&gt;
      &lt;archives&gt;
        &lt;zips&gt;
          &lt;restrict&gt;
            &lt;path path="${java.class.path}"/&gt;
            &lt;name name="*.jar"/&gt;
          &lt;/restrict&gt;
        &lt;/zips&gt;
      &lt;/archives&gt;
    &lt;/copy&gt;
  </pre>
 </blockquote>

 </body>
 </html>
--- a/src/tests/antunit/types/resources/archives-test.xml
+++ b/src/tests/antunit/types/resources/archives-test.xml
@@ -93,4 +93,44 @@
    </au:expectfailure>
  </target>    

  <!-- works but takes a veeeeeery long time -->
  <target name="XtestResourcesManualExample">
    <mkdir dir="${output}"/>
    <copy todir="${output}">
      <archives>
        <zips>
          <restrict>
            <path path="${java.class.path}"/>
            <name name="*.jar"/>
          </restrict>
        </zips>
      </archives>
    </copy>
    <au:assertFileExists
       file="${output}/org/apache/tools/ant/launch/Launcher.class"/>
  </target>

  <target name="testZipManualExample">
    <mkdir dir="${output}/control"/>
    <mkdir dir="${input}/htdocs/manual"/>
    <touch file="${input}/htdocs/manual/foo.txt"/>
    <zip destfile="${input}/examples-a.zip">
      <fileset dir="." includes="*.xml"/>
    </zip>
    <zip destfile="${output}/manual.zip">
      <mappedresources>
        <fileset dir="${input}/htdocs/manual"/>
        <globmapper from="*" to="docs/user-guide/*"/>
      </mappedresources>
      <archives>
        <zips>
          <fileset dir="${input}" includes="examples*.zip"/>
        </zips>
      </archives>
    </zip>
    <unzip src="${output}/manual.zip" dest="${output}/control"/>
    <au:assertFileExists file="${output}/control/archives-test.xml"/>
    <au:assertFileExists file="${output}/control/docs/user-guide/foo.txt"/>
  </target>

 </project>