Jar

說明

將一組檔案打包成 Jar。

basedir 屬性是打包 Jar 的參考目錄。

請注意，檔案權限不會儲存在產生的 jar 檔中。

可以調整要打包成 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 屬性或具有單一 classname 屬性的巢狀 <provider> 元素指定。如果 JAR 檔案有多個服務實作，可以使用多個巢狀 <provider> 元素。

範例

簡單

將 ${build}/classes 目錄中的所有檔案封裝成 JAR 檔案，稱為 app.jar，並儲存在 ${dist}/lib 目錄中。

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

使用篩選器

將 ${build}/classes 目錄中的所有檔案封裝成 JAR 檔案，稱為 app.jar，並儲存在 ${dist}/lib 目錄中。名稱為 Test.class 的檔案會被排除。

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

將 ${build}/classes 目錄中的所有檔案封裝成 JAR 檔案，稱為 app.jar，並儲存在 ${dist}/lib 目錄中。僅使用 mypackage/test 目錄下的檔案，並排除名稱為 Test.class 的檔案。

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

多個檔案集

將 ${build}/classes 目錄和 ${src}/resources 目錄中的所有檔案封裝成 JAR 檔案，稱為 app.jar，並儲存在 ${dist}/lib 目錄中。名稱為 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>

合併檔案

建立一個主類別為 com.acme.checksites.Main 的可執行 JAR 檔案，並嵌入 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>

建立一個主類別為 com.acme.checksites.Main 的可執行 JAR 檔案，並嵌入 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>