root/release-kits/lirk3/bin/ant-installer/web/manual/manual/CoreTasks/jar.html @ 14982

Revision 14982, 17.9 KB (checked in by oranfry, 11 years ago)

initial import of LiRK3

Line 
1<!--
2   Licensed to the Apache Software Foundation (ASF) under one or more
3   contributor license agreements.  See the NOTICE file distributed with
4   this work for additional information regarding copyright ownership.
5   The ASF licenses this file to You under the Apache License, Version 2.0
6   (the "License"); you may not use this file except in compliance with
7   the License.  You may obtain a copy of the License at
8
9       http://www.apache.org/licenses/LICENSE-2.0
10
11   Unless required by applicable law or agreed to in writing, software
12   distributed under the License is distributed on an "AS IS" BASIS,
13   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   See the License for the specific language governing permissions and
15   limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Jar Task</title>
23</head>
24
25<body>
26
27<h2><a name="jar">Jar</a></h2>
28<h3>Description</h3>
29<p>Jars a set of files.</p>
30<p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>
31<p>Note that file permissions will not be stored in the resulting jarfile.</p>
32<p>It is possible to refine the set of files that are being jarred. This can be
33done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
34attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
35have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
36the files you want to have excluded. This is also done with patterns. And
37finally with the <i>defaultexcludes</i> attribute, you can specify whether you
38want to use default exclusions or not. See the section on <a
39href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
40inclusion/exclusion of files works, and how to write patterns.</p>
41<p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
42supports all attributes of <code>&lt;fileset&gt;</code>
43(<code>dir</code> becomes <code>basedir</code>) as well as the nested
44<code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
45<code>&lt;patternset&gt;</code> elements.</p>
46<p>You can also use nested file sets for more flexibility, and specify
47multiple ones to merge together different trees of files into one JAR.
48The extended fileset and groupfileset child elements from the zip task are
49also available in the jar task.
50See the <a href="zip.html">Zip</a> task for more details and examples.</p>
51<p>If the manifest is omitted, a simple one will be supplied by Ant.</p>
52
53<p>The <code>update</code> parameter controls what happens if the JAR
54file already exists. When set to <code>yes</code>, the JAR file is
55updated with the files specified. When set to <code>no</code> (the
56default) the JAR file is overwritten. An example use of this is
57provided in the <a href="zip.html">Zip task documentation</a>.  Please
58note that ZIP files store file modification times with a granularity
59of two seconds.  If a file is less than two seconds newer than the
60entry in the archive, Ant will not consider it newer.</p>
61
62<p>The <code>whenmanifestonly</code> parameter controls what happens when no
63files, apart from the manifest file, or nested services, match.
64If <code>skip</code>, the JAR is not created and a warning is issued.
65If <code>fail</code>, the JAR is not created and the build is halted with an error.
66If <code>create</code>, (default) an empty JAR file (only containing a manifest and services)
67is created.</p>
68
69<p>(The Jar task is a shortcut for specifying the manifest file of a JAR file.
70The same thing can be accomplished by using the <i>fullpath</i>
71attribute of a zipfileset in a Zip task. The one difference is that if the
72<i>manifest</i> attribute is not specified, the Jar task will
73include an empty one for you.)</p>
74
75<p>Manifests are processed by the Jar task according to the
76<a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html">Jar file specification.</a>
77Note in particular that this may result in manifest lines greater than 72 bytes
78being wrapped and continued on the next line.
79</p>
80
81<p><b>Please note that the zip format allows multiple files of the same
82fully-qualified name to exist within a single archive.  This has been
83documented as causing various problems for unsuspecting users.  If you wish
84to avoid this behavior you must set the <code>duplicate</code> attribute
85to a value other than its default, <code>"add"</code>.</b></p>
86
87<h3>Parameters</h3>
88<table border="1" cellpadding="2" cellspacing="0">
89  <tr>
90    <td valign="top"><b>Attribute</b></td>
91    <td valign="top"><b>Description</b></td>
92    <td align="center" valign="top"><b>Required</b></td>
93  </tr>
94  <tr>
95    <td valign="top">destfile</td>
96    <td valign="top">the JAR file to create.</td>
97    <td valign="top" align="center">Yes</td>
98  </tr>
99  <tr>
100    <td valign="top">basedir</td>
101    <td valign="top">the directory from which to jar the files.</td>
102    <td valign="top" align="center">No</td>
103  </tr>
104  <tr>
105    <td valign="top">compress</td>
106    <td valign="top">Not only store data but also compress them,
107    defaults to true.  Unless you set the <em>keepcompression</em>
108    attribute to false, this will apply to the entire archive, not
109    only the files you've added while updating.</td>
110    <td align="center" valign="top">No</td>
111  </tr>
112  <tr>
113    <td valign="top">keepcompression</td>
114    <td valign="top">For entries coming from existing archives (like
115    nested <em>zipfileset</em>s or while updating the archive), keep
116    the compression as it has been originally instead of using the
117    <em>compress</em> attribute.  Defaults false.  <em>Since Ant
118    1.6</em></td>
119    <td align="center" valign="top">No</td>
120  </tr>
121  <tr>
122    <td valign="top">encoding</td>
123    <td valign="top">The character encoding to use for filenames
124      inside the archive.  Defaults to UTF8. <strong>It is not
125      recommended to change this value as the created archive will most
126      likely be unreadable for Java otherwise.</strong></td>
127    <td align="center" valign="top">No</td>
128  </tr>
129  <tr>
130    <td valign="top">filesonly</td>
131    <td valign="top">Store only file entries, defaults to false</td>
132    <td align="center" valign="top">No</td>
133  </tr>
134  <tr>
135    <td valign="top">includes</td>
136    <td valign="top">comma- or space-separated list of patterns of files that must be
137      included. All files are included when omitted.</td>
138    <td valign="top" align="center">No</td>
139  </tr>
140  <tr>
141    <td valign="top">includesfile</td>
142    <td valign="top">the name of a file. Each line of this file is
143      taken to be an include pattern</td>
144    <td valign="top" align="center">No</td>
145  </tr>
146  <tr>
147    <td valign="top">excludes</td>
148    <td valign="top">comma- or space-separated list of patterns of files that must be
149      excluded. No files (except default excludes) are excluded when omitted.</td>
150    <td valign="top" align="center">No</td>
151  </tr>
152  <tr>
153    <td valign="top">excludesfile</td>
154    <td valign="top">the name of a file. Each line of this file is
155      taken to be an exclude pattern</td>
156    <td valign="top" align="center">No</td>
157  </tr>
158  <tr>
159    <td valign="top">defaultexcludes</td>
160    <td valign="top">indicates whether default excludes should be used or not
161      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
162    <td valign="top" align="center">No</td>
163  </tr>
164  <tr>
165    <td valign="top">manifest</td>
166    <td valign="top">the manifest file to use.  This can be either the location of a manifest, or the name of a jar added through a fileset.  If its the name of an added jar, the task expects the manifest to be in the jar at META-INF/MANIFEST.MF</td>
167    <td valign="top" align="center">No</td>
168  </tr>
169  <tr>
170    <td valign="top">filesetmanifest</td>
171    <td valign="top">behavior when a Manifest is found in a zipfileset or zipgroupfileset file is found.  Valid values are &quot;skip&quot;, &quot;merge&quot;, and &quot;mergewithoutmain&quot;.  &quot;merge&quot; will merge all of the manifests together, and merge this into any other specified manifests.  &quot;mergewithoutmain&quot; merges everything but the Main section of the manifests.  Default value is &quot;skip&quot;.
172    </td>
173    <td valign="top" align="center">No</td>
174  </tr>
175  <tr>
176    <td valign="top">update</td>
177    <td valign="top">indicates whether to update or overwrite
178      the destination file if it already exists.  Default is &quot;false&quot;.</td>
179    <td valign="top" align="center">No</td>
180  </tr>
181  <tr>
182    <td valign="top">whenmanifestonly</td>
183    <td valign="top">behavior when no files match.  Valid values are &quot;fail&quot;, &quot;skip&quot;, and &quot;create&quot;.  Default is &quot;create&quot;.</td>
184    <td valign="top" align="center">No</td>
185  </tr>
186  <tr>
187    <td valign="top">duplicate</td>
188    <td valign="top">behavior when a duplicate file is found.  Valid values are &quot;add&quot;, &quot;preserve&quot;, and &quot;fail&quot;.  The default value is &quot;add&quot;.  </td>
189    <td valign="top" align="center">No</td>
190  </tr>
191  <tr>
192    <td valign="top">index</td>
193    <td valign="top">whether to create an <A
194    HREF="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR%20Index">index
195    list</A> to speed up classloading.  This is a JDK 1.3+ specific
196    feature.  Unless you specify additional jars with nested <a
197    href="#indexjars"><code>indexjars</code></a> elements, only the
198    contents of this jar will be included in the index.  Defaults to
199    false.</td>
200    <td valign="top" align="center">No</td>
201  </tr>
202  <tr>
203    <td valign="top">manifestencoding</td>
204    <td valign="top">The encoding used to read the JAR manifest, when a manifest file is specified.</td>
205    <td valign="top" align="center">No, defaults to the platform encoding.</td>
206  </tr>
207  <tr>
208    <td valign="top">roundup</td>
209    <td valign="top">Whether the file modification times will be
210    rounded up to the next even number of seconds.<br>
211    Zip archives store file modification times with a granularity of
212    two seconds, so the times will either be rounded up or down.  If
213    you round down, the archive will always seem out-of-date when you
214    rerun the task, so the default is to round up.  Rounding up may
215    lead to a different type of problems like JSPs inside a web
216    archive that seem to be slightly more recent than precompiled
217    pages, rendering precompilation useless.<br>
218    Defaults to true.  <em>Since Ant 1.6.2</em></td>
219    <td align="center" valign="top">No</td>
220  </tr>
221  <tr>
222    <td valign="top">level</td>
223    <td valign="top">Non-default level at which file compression should be
224    performed. Valid values range from 0 (no compression/fastest) to 9
225    (maximum compression/slowest). <em>Since Ant 1.7</em></td>
226    <td valign="top" align="center">No</td>
227  </tr>
228</table>
229
230<h3>Nested elements</h3>
231<h4>metainf</h4>
232<p>The nested <code>metainf</code> element specifies a <a
233href="../CoreTypes/fileset.html">FileSet</a>. All files included in this fileset will
234end up in the <code>META-INF</code> directory of the jar file. If this
235fileset includes a file named <code>MANIFEST.MF</code>, the file is
236ignored and you will get a warning.</p>
237
238<h4>manifest</h4>
239<p>The manifest nested element allows the manifest for the Jar file to
240be provided inline in the build file rather than in an external
241file. This element is identical to the
242<a href="manifest.html">manifest</a> task, but the file and mode
243attributes must be omitted.</p>
244<p>
245If both an inline manifest and an external file are both specified, the
246manifests are merged.
247</p>
248
249<p>When using inline manifests, the Jar task will check whether the manifest
250contents have changed (i.e. the manifest as specified is different in any way
251from the manifest that exists in the Jar, if it exists.
252If the manifest values have changed the jar will be updated or rebuilt, as
253appropriate.
254</p>
255
256<a name="indexjars"><h4>indexjars</h4></a>
257
258<p><em>since ant 1.6.2</em></p>
259
260<p>The nested <code>indexjars</code> element specifies a <a
261href="../using.html#path">PATH like structure</a>.  Its content is
262completely ignored unless you set the index attribute of the task to
263true.</p>
264
265<p>The index created by this task will contain indices for the
266archives contained in this path, the names used for the archioves
267depend on your manifest:</p>
268<ul>
269  <li>If the generated jar's manifest contains no Class-Path
270  attribute, the file name without any leading directory path will be
271  used and all parts of the path will get indexed.</li>
272  <li>If the manifest contains a Class-Path attribute, this task will
273  try to guess which part of the Class-Path belongs to a given
274  archive.  If it cannot guess a name, the archive will be skipped,
275  otherwise tha name listed inside the Class-PAth attribute will be
276  used.</li>
277</ul>
278
279<p>This task will not create any index entries for archives that are
280empty or only contain files inside the META-INF directory.</p>
281<a name="service"><h4>service</h4></a>
282
283<p><em>since ant 1.7.0</em></p>
284
285<p>
286  The nested <code>service</code> element specifies a service.
287  Services are described by
288  <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider">http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#Service%20Provider</a>.
289  The approach is to have providers JARs include files named by the service
290  provided, for example,
291  META-INF/services/javax.script.ScriptEngineFactory
292  which can include implementation class names, one per line (usually just one per JAR).
293
294  The name of the
295  service is set by the "type" attribute. The classname implementing
296  the service is the the "provider" attribute, or it one wants to
297  specify a number of classes that implement the service, by
298  "provider" nested elements.
299</p>
300<p>
301<table border="1" cellpadding="2" cellspacing="0">
302  <tr>
303    <td valign="top"><b>Attribute</b></td>
304    <td valign="top"><b>Description</b></td>
305    <td align="center" valign="top"><b>Required</b></td>
306  </tr>
307  <tr>
308    <td valign="top">type</td>
309    <td valign="top">The name of the service.</td>
310    <td valign="top" align="center">Yes</td>
311  </tr>
312  <tr>
313    <td valign="top">provider</td>
314    <td valign="top">
315      The classname of the class implemening the service.
316    </td>
317    <td valign="top" align="center">Yes, unless there is a nested
318      <code>&lt;provider&gt;</code> element.</td>
319  </tr>
320</table>
321  <p>
322    The provider classname is specified either by the "provider" attribute, or
323    by a nested &lt;provider&gt; element, which has a single "classname" attribute.
324    If a JAR file has more that one implementation of the service, a number of
325    nested &lt;provider&gt; elements may be used.
326  </p>
327<h3>Examples</h3>
328<pre>  &lt;jar destfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot;/&gt;</pre>
329<p>jars all files in the <code>${build}/classes</code> directory into a file
330called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
331<pre>  &lt;jar destfile=&quot;${dist}/lib/app.jar&quot;
332       basedir=&quot;${build}/classes&quot;
333       excludes=&quot;**/Test.class&quot;
334  /&gt;</pre>
335<p>jars all files in the <code>${build}/classes</code> directory into a file
336called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files
337with the name <code>Test.class</code> are excluded.</p>
338<pre>  &lt;jar destfile=&quot;${dist}/lib/app.jar&quot;
339       basedir=&quot;${build}/classes&quot;
340       includes=&quot;mypackage/test/**&quot;
341       excludes=&quot;**/Test.class&quot;
342  /&gt;</pre>
343<p>jars all files in the <code>${build}/classes</code> directory into a file
344called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only
345files under the directory <code>mypackage/test</code> are used, and files with
346the name <code>Test.class</code> are excluded.</p>
347<pre>  &lt;jar destfile=&quot;${dist}/lib/app.jar&quot;&gt;
348    &lt;fileset dir=&quot;${build}/classes&quot;
349             excludes=&quot;**/Test.class&quot;
350    /&gt;
351    &lt;fileset dir=&quot;${src}/resources&quot;/&gt;
352  &lt;/jar&gt;</pre>
353<p>jars all files in the <code>${build}/classes</code> directory and also
354in the <code>${src}/resources</code> directory together into a file
355called <code>app.jar</code> in the <code>${dist}/lib</code> directory.
356Files with the name <code>Test.class</code> are excluded.
357If there are files such as <code>${build}/classes/mypackage/MyClass.class</code>
358and <code>${src}/resources/mypackage/image.gif</code>, they will appear
359in the same directory in the JAR (and thus be considered in the same package
360by Java).</p>
361
362<pre>  &lt;jar destfile=&quot;test.jar&quot; basedir=&quot;.&quot;&gt;
363    &lt;include name=&quot;build&quot;/&gt;
364    &lt;manifest&gt;
365      &lt;attribute name=&quot;Built-By&quot; value=&quot;${user.name}&quot;/&gt;
366      &lt;section name=&quot;common/class1.class&quot;&gt;
367        &lt;attribute name=&quot;Sealed&quot; value=&quot;false&quot;/&gt;
368      &lt;/section&gt;
369    &lt;/manifest&gt;
370  &lt;/jar&gt;</pre>
371<p>
372This is an example of an inline manifest specification. Note that the Built-By
373attribute will take the value of the Ant property ${user.name}. The manifest
374produced by the above would look like this:
375</p>
376<pre><code>Manifest-Version: 1.0
377Built-By: conor
378Created-By: Apache Ant 1.6.5
379
380Name: common/MyClass.class
381Sealed: false</code></pre>
382
383
384<p>
385  The following shows how to create a jar file specifing a service
386  with an implementation of the JDK6 scripting interface:
387</p>
388<blockquote><pre>&lt;jar jarfile="pinky.jar"&gt;
389  &lt;fileset dir="build/classes"/&gt;
390  &lt;service type="javax.script.ScriptEngineFactory"
391           provider="org.acme.PinkyLanguage"/&gt;
392&lt;/jar&gt;
393</pre></blockquote>
394<p>
395  The following shows how to create a jar file specifing a service
396  with two implementations of the JDK6 scripting interface:
397</p>
398<blockquote><pre>
399&lt;jar jarfile="pinkyandbrain.jar"&gt;
400  &lt;fileset dir="classes"/&gt;
401  &lt;service type="javax.script.ScriptEngineFactory"&gt;
402    &lt;provider classname="org.acme.PinkyLanguage"/&gt;
403    &lt;provider classname="org.acme.BrainLanguage"/&gt;
404  &lt;/service&gt;
405&lt;/jar&gt;
406</pre></blockquote>
407</body>
408</html>
Note: See TracBrowser for help on using the browser.