Jar

描述

将一组文件打包成 Jar 包。

basedir 属性是打包的参考目录。

请注意，生成的 Jar 包中不会存储文件权限。

可以对要打包的文件进行细化。这可以通过 includes、includesfile、excludes、excludesfile 和 defaultexcludes 属性来实现。使用 includes 或 includesfile 属性，您可以使用模式指定要包含的文件。使用 exclude 或 excludesfile 属性指定要排除的文件。这也使用模式来完成。最后，使用 defaultexcludes 属性，您可以指定是否使用默认排除。有关如何进行文件包含/排除以及如何编写模式，请参阅有关 基于目录的任务 的部分。

此任务形成一个隐式的 FileSet，并支持 <fileset> 的大多数属性（dir 变为 basedir），以及嵌套的 <include>、<exclude> 和 <patternset> 元素。

您还可以使用嵌套的文件集来获得更大的灵活性，并指定多个文件集将不同的文件树合并到一个 JAR 中。zip 任务中的扩展 fileset 和 groupfileset 子元素在 jar 任务中也可用。有关更多详细信息和示例，请参阅 Zip 任务。

update 参数控制如果 JAR 文件已经存在会发生什么。如果设置为 yes，则使用指定的文件更新 JAR 文件。如果设置为 no（默认值），则覆盖 JAR 文件。在 Zip 任务文档 中提供了此功能的示例用法。请注意，ZIP 文件以 2 秒的粒度存储文件修改时间。如果文件比存档中的条目新不到 2 秒，Ant 不会将其视为更新。

如果省略清单，Apache Ant 将提供一个简单的清单。

whenmanifestonly 参数控制当除了清单文件或嵌套服务之外没有文件匹配时会发生什么。如果为 skip，则不创建 JAR 并发出警告。如果为 fail，则不创建 JAR 并使用错误停止构建。如果为 create（默认值），则创建一个空 JAR 文件（仅包含清单和服务）。

（Jar 任务有一个用于指定 JAR 文件的清单文件的快捷方式。使用 Zip 任务中 zipfileset 的 fullpath 属性可以实现相同的效果。唯一的区别是，如果未指定 manifest 属性，Jar 任务将为您包含一个空的清单。）

清单由 Jar 任务根据 Jar 文件规范 进行处理。特别要注意，这可能会导致大于 72 字节的清单行被换行并继续到下一行。

Jar 任务检查您是否根据 版本控制规范 指定了包信息。

请注意，ZIP 格式允许在单个存档中存在多个具有相同完全限定名称的文件。这已被记录为对毫无戒心的用户造成各种问题。如果您希望避免这种行为，则必须将 duplicate 属性设置为除其默认值 add 之外的其他值。

要对 JAR 文件进行加密签名，请使用此任务创建的 JAR 上的 SignJar 任务。

要创建 JEP 238 多版本 jar 的简单版本，您不需要任何特殊工具。只需设置所需的 manifest 条目并将文件放置在所需的位置，如 JEP 238 示例 中所示。如果您想调整这种类型的 jar，例如通过从版本分支中删除“相同”类来减小大小，您需要做更多的事情...

参数

作为嵌套元素指定的参数

metainf

嵌套的 metainf 元素指定一个 FileSet。此文件集中包含的所有文件最终将位于 jar 文件的 META-INF 目录中。如果此文件集包含一个名为 MANIFEST.MF 的文件，则该文件将被忽略，您将收到警告。

manifest

嵌套的manifest元素允许在构建文件中内联提供 Jar 文件的清单，而不是在外部文件中。此元素与manifest任务相同，但必须省略file和mode属性。

如果同时指定了内联清单和外部文件，则会合并这些清单。

使用内联清单时，Jar任务将检查清单内容是否已更改（即，指定的清单是否与 jar 中存在的清单（如果存在）有任何不同。如果清单值已更改，则将根据需要更新或重建 jar。

indexjars

自 Ant 1.6.2 起

嵌套的indexjars元素指定一个类似路径的结构。除非将任务的index属性设置为true，否则其内容将被完全忽略。

此任务创建的索引将包含此路径中包含的存档的索引，用于存档的名称取决于您的清单

• 如果生成的 jar 的清单不包含Class-Path属性，则将使用没有任何前导目录路径的文件名，并且路径的所有部分都将被索引。
• 如果清单包含Class-Path属性，此任务将尝试猜测Class-Path的哪一部分属于给定的存档。如果无法猜测名称，则将跳过存档，否则将使用Class-Path属性中列出的名称。

此任务不会为为空或仅包含META-INF目录中的文件的存档创建任何索引条目，除非indexmetainf属性已设置为true。

indexjarsmapper

自 Ant 1.10.9 起

如果默认文件名转换不足，则可以使用嵌套的indexjarsmapper元素对indexjars指定的存档执行自定义文件名转换。

service

自 Ant 1.7.0 起

嵌套的service元素指定一个服务。服务在服务提供者概述中进行了描述。该方法是让提供者 JAR 包含以提供的服务命名的文件，例如META-INF/services/javax.script.ScriptEngineFactory，其中可以包含实现类名，每行一个（通常每个 JAR 只有一个）。

服务的名称由type属性设置。实现服务的类名是provider属性，或者如果要指定多个实现服务的类，则通过provider嵌套元素。

提供者类名由provider属性或嵌套的<provider>元素指定，该元素具有单个classname属性。如果 JAR 文件具有多个服务的实现，则可以使用多个嵌套的<provider>元素。

示例

简单

将${build}/classes目录中的所有文件打包到${dist}/lib目录中名为app.jar的文件中。

<jar destfile="${dist}/lib/app.jar" basedir="${build}/classes"/>

使用过滤器

将${build}/classes目录中的所有文件打包到${dist}/lib目录中名为app.jar的文件中。排除名为Test.class的文件。

<jar destfile="${dist}/lib/app.jar"
     basedir="${build}/classes"
     excludes="**/Test.class"/>

将${build}/classes目录中的所有文件打包到${dist}/lib目录中名为app.jar的文件中。仅使用mypackage/test目录下的文件，并排除名为Test.class的文件。

<jar destfile="${dist}/lib/app.jar"
     basedir="${build}/classes"
     includes="mypackage/test/**"
     excludes="**/Test.class"/>

多个文件集

将${build}/classes目录和${src}/resources目录中的所有文件一起打包到${dist}/lib目录中名为app.jar的文件中。排除名为Test.class的文件。如果存在诸如${build}/classes/mypackage/MyClass.class和${src}/resources/mypackage/image.gif的文件，它们将出现在 jar 中的同一目录中（因此被 Java 视为同一包）。

<jar destfile="${dist}/lib/app.jar">
    <fileset dir="${build}/classes"
             excludes="**/Test.class"/>
    <fileset dir="${src}/resources"/>
</jar>

合并存档

创建一个可执行的 jar 文件，其主类为com.acme.checksites.Main，并将来自 jar lib/main/some.jar 的所有类嵌入其中。

<jar destfile="build/main/checksites.jar">
    <fileset dir="build/main/classes"/>
    <zipfileset includes="**/*.class" src="lib/main/some.jar"/>
    <manifest>
      <attribute name="Main-Class"
                 value="com.acme.checksites.Main"/>
    </manifest>
</jar>

创建一个可执行的 jar 文件，其主类为com.acme.checksites.Main，并将来自lib/main中所有 jar 的所有类嵌入其中。

<jar destfile="build/main/checksites.jar">
    <fileset dir="build/main/classes"/>
    <restrict>
       <name name="**/*.class"/>
       <archives>
           <zips>
               <fileset dir="lib/main" includes="**/*.jar"/>
           </zips>
       </archives>
    </restrict>
    <manifest>
        <attribute name="Main-Class"
              value="com.acme.checksites.Main"/>
    </manifest>
</jar>

内联清单

<jar destfile="test.jar" basedir=".">
    <include name="build"/>
    <manifest>
        <!-- If this is an Applet or Web Start application, include
             the proper attributes from https://docs.oracle.com/javase/8/docs/technotes/guides/jweb/index.html -->
        <attribute name="Permissions" value="sandbox"/>
        <attribute name="Codebase" value="example.com"/>
        <!-- Who is building this jar? -->
        <attribute name="Built-By" value="${user.name}"/>
        <!-- Information about the program itself -->
        <attribute name="Implementation-Vendor" value="ACME inc."/>
        <attribute name="Implementation-Title" value="GreatProduct"/>
        <attribute name="Implementation-Version" value="1.0.0beta2"/>
        <!-- details -->
        <section name="common/MyClass.class">
            <attribute name="Sealed" value="false"/>
        </section>
    </manifest>
</jar>

这是一个内联清单规范的示例，包括构建程序的版本（Implementation-Version）。请注意，Built-By属性将采用 Ant 属性user.name的值。上面生成的清单将如下所示

Manifest-Version: 1.0
Permissions: sandbox
Codebase: example.com
Built-By: conor
Implementation-Vendor: ACME inc.
Implementation-Title: GreatProduct
Implementation-Version: 1.0.0beta2
Created-By: Apache Ant 1.9.2

Name: common/MyClass.class
Sealed: false

服务提供者

以下显示了如何创建一个 jar 文件，该文件指定一个具有脚本接口实现的服务

<jar destfile="pinky.jar">
    <fileset dir="build/classes"/>
    <service type="javax.script.ScriptEngineFactory"
             provider="org.acme.PinkyLanguage"/>
</jar>

以下显示了如何创建一个 jar 文件，该文件指定一个具有两个脚本接口实现的服务

<jar destfile="pinkyandbrain.jar">
    <fileset dir="classes"/>
    <service type="javax.script.ScriptEngineFactory">
        <provider classname="org.acme.PinkyLanguage"/>
        <provider classname="org.acme.BrainLanguage"/>
    </service>
</jar>

JEP 238 示例：多版本 JAR 文件

在这里，我们希望根据规范JEP 238创建一个多版本 JAR 文件。它在 JAR 之上定义了将附加类或覆盖类放置在 jar 中的可能性，这些类根据您运行的 Java 版本可用。
基本上，它说您必须设置清单条目Multi-Release: true并将所有附加类或覆盖类放置在META-INF/versions/number/package-structure中，例如META-INF/versions/9/org/apache/ant/MyClass.class

在此示例中，我们预计普通类将编译到${java.classes}中，而 Java 9 类将编译到${java9.classes}中。

<jar destfile="mrjar.jar">
    <manifest>
        <!-- special mf-entry according to the spec -->
        <attribute name="Multi-Release" value="true"/>
    </manifest>
    <!-- directory structure according to the spec ... -->
    <!-- ... default classes loadable by old (<Java 9) versions -->
    <fileset dir="${java.classes}"/>
    <!-- ... per release classes, require Java 9+ for loadable via standard ClassLoader -->
    <zipfileset prefix="META-INF/versions/9/" dir="${java9.classes}"/>
</jar>