2001-02-13 12:32:01 +00:00
< html >
< head >
< meta http-equiv = "Content-Language" content = "en-us" >
2002-02-03 22:00:42 +00:00
< title > Jar Task< / title >
2001-02-13 12:32:01 +00:00
< / head >
< body >
< h2 > < a name = "jar" > Jar< / a > < / h2 >
< h3 > Description< / h3 >
< p > Jars a set of files.< / p >
< p > The < i > basedir< / i > attribute is the reference directory from where to jar.< / p >
< p > Note that file permissions will not be stored in the resulting jarfile.< / p >
< p > It is possible to refine the set of files that are being jarred. This can be
done with the < i > includes< / i > , < i > includesfile< / i > , < i > excludes< / i > , < i > excludesfile< / i > and < i > defaultexcludes< / i >
attributes. With the < i > includes< / i > or < i > includesfile< / i > attribute you specify the files you want to
have included by using patterns. The < i > exclude< / i > or < i > excludesfile< / i > attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the < i > defaultexcludes< / i > attribute, you can specify whether you
want to use default exclusions or not. See the section on < a
href="../dirtasks.html#directorybasedtasks">directory based tasks< / a > , on how the
inclusion/exclusion of files works, and how to write patterns.< / p >
< p > This task forms an implicit < a href = "../CoreTypes/fileset.html" > FileSet< / a > and
supports all attributes of < code > < fileset> < / code >
(< code > dir< / code > becomes < code > basedir< / code > ) as well as the nested
< code > < include> < / code > , < code > < exclude> < / code > and
< code > < patternset> < / code > elements.< / p >
< p > You can also use nested file sets for more flexibility, and specify
multiple ones to merge together different trees of files into one JAR.
2003-03-07 14:48:52 +00:00
The extended fileset and groupfileset child elements from the zip task are
2002-03-03 06:52:07 +00:00
also available in the jar task.
2001-02-13 12:32:01 +00:00
See the < a href = "zip.html" > Zip< / a > task for more details and examples.< / p >
2002-07-09 21:06:15 +00:00
< p > If the manifest is omitted, a simple one will be supplied by Ant.< / p >
2003-02-05 10:43:08 +00:00
< p > The < code > update< / code > parameter controls what happens if the JAR
file already exists. When set to < code > yes< / code > , the JAR file is
2001-08-30 13:23:14 +00:00
updated with the files specified. When set to < code > no< / code > (the
default) the JAR file is overwritten. An example use of this is
2003-02-05 10:43:08 +00:00
provided in the < a href = "zip.html" > Zip task documentation< / a > . 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, Ant will not consider it newer.< / p >
2002-06-01 12:26:43 +00:00
< p > (The Jar task is a shortcut for specifying the manifest file of a JAR file.
2001-02-13 12:32:01 +00:00
The same thing can be accomplished by using the < i > fullpath< / i >
attribute of a zipfileset in a Zip task. The one difference is that if the
2002-06-01 12:26:43 +00:00
< i > manifest< / i > attribute is not specified, the Jar task will
2001-02-13 12:32:01 +00:00
include an empty one for you.)< / p >
2002-06-01 12:26:43 +00:00
< p > Manifests are processed by the Jar task according to the
2001-12-12 10:31:25 +00:00
< a href = "http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html" > Jar file specification.< / a >
2002-06-01 12:26:43 +00:00
Note in particular that this may result in manifest lines greater than 72 bytes
2001-12-12 10:31:25 +00:00
being wrapped and continued on the next line.
< / p >
2001-02-13 12:32:01 +00:00
< h3 > Parameters< / h3 >
< table border = "1" cellpadding = "2" cellspacing = "0" >
< tr >
< td valign = "top" > < b > Attribute< / b > < / td >
< td valign = "top" > < b > Description< / b > < / td >
< td align = "center" valign = "top" > < b > Required< / b > < / td >
< / tr >
< tr >
2002-01-07 06:22:11 +00:00
< td valign = "top" > destfile< / td >
< td valign = "top" > the JAR file to create.< / td >
2001-02-13 12:32:01 +00:00
< td valign = "top" align = "center" > Yes< / td >
< / tr >
< tr >
< td valign = "top" > basedir< / td >
< td valign = "top" > the directory from which to jar the files.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > compress< / td >
< td valign = "top" > Not only store data but also compress them, defaults to true< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-07-05 13:10:26 +00:00
< tr >
< td valign = "top" > encoding< / td >
< td valign = "top" > The character encoding to use for filenames
inside the archive. Defaults to UTF8. < strong > It is not
recommended to change this value as the created archive will most
likely be unreadable for Java otherwise.< / strong > < / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-07-12 07:36:50 +00:00
< tr >
< td valign = "top" > filesonly< / td >
< td valign = "top" > Store only file entries, defaults to false< / td >
< td align = "center" valign = "top" > No< / td >
< / tr >
2001-02-13 12:32:01 +00:00
< tr >
< td valign = "top" > includes< / td >
2002-06-22 23:38:38 +00:00
< td valign = "top" > comma- or space-separated list of patterns of files that must be
2001-02-13 12:32:01 +00:00
included. All files are included when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > includesfile< / td >
< td valign = "top" > the name of a file. Each line of this file is
taken to be an include pattern< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > excludes< / td >
2002-06-22 23:38:38 +00:00
< td valign = "top" > comma- or space-separated list of patterns of files that must be
2001-02-13 12:32:01 +00:00
excluded. No files (except default excludes) are excluded when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > excludesfile< / td >
< td valign = "top" > the name of a file. Each line of this file is
taken to be an exclude pattern< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > defaultexcludes< / td >
< td valign = "top" > indicates whether default excludes should be used or not
(" yes" /" no" ). Default excludes are used when omitted.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > manifest< / td >
2002-03-03 06:52:07 +00:00
< 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 >
< td valign = "top" align = "center" > No< / td >
< / tr >
2002-11-21 21:47:53 +00:00
< tr >
< td valign = "top" > filesetmanifest< / td >
< td valign = "top" > behavior when a Manifest is found in a zipfileset or zipgroupfileset file is found. Valid values are " skip" , " merge" , and " mergewithoutmain" . " merge" will merge all of the manifests together, and merge this into any other specified manifests. " mergewithoutmain" merges everything but the Main section of the manifests. Default value is " skip" .
< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
2001-08-30 13:23:14 +00:00
< tr >
< td valign = "top" > update< / td >
< td valign = "top" > indicates whether to update or overwrite
the destination file if it already exists.< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
2002-03-03 06:52:07 +00:00
< tr >
< td valign = "top" > whenempty< / td >
< td valign = "top" > behavior when no files match. Valid values are " fail" , " skip" , and " create" . Default is " skip" .< / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > duplicate< / td >
< td valign = "top" > behavior when a duplicate file is found. Valid values are " add" , " preserve" , and " fail" . The default value is " add" . < / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
< tr >
< td valign = "top" > index< / td >
< td valign = "top" > whether to create an < A HREF = "http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR%20Index" > index list< / A > to speed up classloading. This is a JDK 1.3+ specific feature. Defaults to false. < / td >
< td valign = "top" align = "center" > No< / td >
< / tr >
2001-02-13 12:32:01 +00:00
< / table >
2001-12-12 10:31:25 +00:00
2001-04-04 13:35:05 +00:00
< h3 > Nested elements< / h3 >
< h4 > metainf< / h4 >
< p > The nested < code > metainf< / code > element specifies a < a
href="../CoreTypes/fileset.html">FileSet< / a > . All files included in this fileset will
end up in the < code > META-INF< / code > directory of the jar file. If this
fileset includes a file named < code > MANIFEST.MF< / code > , the file is
ignored and you will get a warning.< / p >
2001-12-12 10:31:25 +00:00
2002-06-01 12:26:43 +00:00
< h4 > manifest< / h4 >
2001-12-12 11:05:34 +00:00
< p > The manifest nested element allows the manifest for the Jar file to
be provided inline in the build file rather than in an external
2002-06-01 12:26:43 +00:00
file. This element is identical to the
2003-01-02 13:26:35 +00:00
< a href = "manifest.html" > manifest< / a > task, but the file and mode
attributes must be omitted.< / p >
2001-12-12 10:31:25 +00:00
< p >
If both an inline manifest and an external file are both specified, the
2002-06-01 12:26:43 +00:00
manifests are merged.
2001-12-12 10:31:25 +00:00
< / p >
< p > When using inline manifests, the Jar task will check whether the build
file is more recent that the Jar file when deciding whether to rebuild the
2002-06-01 12:26:43 +00:00
Jar. This will not take into account property file changes which may affect
2001-12-12 10:31:25 +00:00
the resulting Jar.
< / p >
2001-02-13 12:32:01 +00:00
< h3 > Examples< / h3 >
2002-06-01 12:26:43 +00:00
< pre > < jar destfile=" ${dist}/lib/app.jar" basedir=" ${build}/classes" /> < / pre >
2001-02-13 12:32:01 +00:00
< p > jars all files in the < code > ${build}/classes< / code > directory into a file
called < code > app.jar< / code > in the < code > ${dist}/lib< / code > directory.< / p >
2002-01-07 06:22:11 +00:00
< pre > < jar destfile=" ${dist}/lib/app.jar"
2001-02-13 12:32:01 +00:00
basedir=" ${build}/classes"
excludes=" **/Test.class"
/> < / pre >
< p > jars all files in the < code > ${build}/classes< / code > directory into a file
called < code > app.jar< / code > in the < code > ${dist}/lib< / code > directory. Files
with the name < code > Test.class< / code > are excluded.< / p >
2002-01-07 06:22:11 +00:00
< pre > < jar destfile=" ${dist}/lib/app.jar"
2001-02-13 12:32:01 +00:00
basedir=" ${build}/classes"
includes=" mypackage/test/**"
excludes=" **/Test.class"
/> < / pre >
< p > jars all files in the < code > ${build}/classes< / code > directory into a file
called < code > app.jar< / code > in the < code > ${dist}/lib< / code > directory. Only
files under the directory < code > mypackage/test< / code > are used, and files with
the name < code > Test.class< / code > are excluded.< / p >
2002-01-07 06:22:11 +00:00
< pre > < jar destfile=" ${dist}/lib/app.jar" >
2001-02-13 12:32:01 +00:00
< fileset dir=" ${build}/classes"
excludes=" **/Test.class"
/>
< fileset dir=" ${src}/resources" />
< /jar> < / pre >
< p > jars all files in the < code > ${build}/classes< / code > directory and also
in the < code > ${src}/resources< / code > directory together into a file
called < code > app.jar< / code > in the < code > ${dist}/lib< / code > directory.
Files with the name < code > Test.class< / code > are excluded.
If there are files such as < code > ${build}/classes/mypackage/MyClass.class< / code >
and < code > ${src}/resources/mypackage/image.gif< / code > , they will appear
in the same directory in the JAR (and thus be considered in the same package
by Java).< / p >
2002-01-07 06:22:11 +00:00
< pre > < jar destfile=" test.jar" basedir=" ." >
2001-12-12 10:31:25 +00:00
< include name=" build" />
< manifest>
< attribute name=" Built-By" value=" ${user.name}" />
< section name=" common/class1.class" >
< attribute name=" Sealed" value=" false" />
< /section>
< /manifest>
< /jar> < / pre >
< p >
This is an example of an inline manifest specification. Note that the Built-By
2002-06-01 12:26:43 +00:00
attribute will take the value of the Ant property ${user.name}. The manifest
2001-12-12 10:31:25 +00:00
produced by the above would look like this:
< / p >
< pre > < code > Manifest-Version: 1.0
Built-By: conor
Created-By: Apache Ant 1.5alpha
Name: common/class1.class
Sealed: false< / code > < / pre >
2001-02-13 12:32:01 +00:00
< hr >
2003-01-06 07:32:35 +00:00
< p align = "center" > Copyright © 2000-2003 Apache Software Foundation. All rights
2001-02-13 12:32:01 +00:00
Reserved.< / p >
< / body >
< / html >
