應用程式外掛程式 - Gradle 繁體中文

應用程式外掛程式有助於建立可執行 JVM 應用程式。它讓您可以在開發期間輕鬆地在本地啟動應用程式，並將應用程式封裝成 TAR 和/或 ZIP，包括特定於作業系統的啟動指令碼。

套用應用程式外掛程式也會隱含套用 Java 外掛程式。main 來源組實際上就是「應用程式」。

套用應用程式外掛程式也會隱含套用發行版外掛程式。會建立一個封裝應用程式（包括程式碼相依性和產生的啟動指令碼）的 main 發行版。

建置 JVM 應用程式

若要使用應用程式外掛程式，請在您的建置指令碼中包含下列內容

build.gradle.kts

plugins {
    application
}

build.gradle

plugins {
    id 'application'
}

此外掛程式唯一的強制設定是應用程式的 main 類別（亦即進入點）的規格。

範例 2. 設定應用程式 main 類別

build.gradle.kts

application {
    mainClass = "org.gradle.sample.Main"
}

build.gradle

application {
    mainClass = 'org.gradle.sample.Main'
}

你可以透過執行 run 任務（類型：JavaExec）來執行應用程式。這會編譯主來源組，並使用指定的 main 類別，以其類別（連同所有執行時期相依項）作為類別路徑，啟動新的 JVM。你可以使用 gradle run --debug-jvm 以偵錯模式啟動應用程式（請參閱 JavaExec.setDebug(boolean)）。

自 Gradle 4.9 起，命令列引數可以使用 --args 傳遞。例如，如果你想使用命令列引數 foo --bar 啟動應用程式，你可以使用 gradle run --args="foo --bar"（請參閱 JavaExec.setArgsString(java.lang.String)）。

如果你的應用程式需要特定組的 JVM 設定或系統屬性，你可以設定 applicationDefaultJvmArgs 屬性。這些 JVM 引數會套用至 run 任務，並在你的發行版的產生啟動指令碼中考量。

範例 3. 設定預設 JVM 設定

build.gradle.kts

application {
    applicationDefaultJvmArgs = listOf("-Dgreeting.language=en")
}

build.gradle

application {
    applicationDefaultJvmArgs = ['-Dgreeting.language=en']
}

如果你的應用程式的啟動指令碼應該在與 bin 不同的目錄中，你可以設定 executableDir 屬性。

範例 4. 設定啟動指令碼的客製化目錄

build.gradle.kts

application {
    executableDir = "custom_bin_dir"
}

build.gradle

application {
    executableDir = 'custom_bin_dir'
}

使用 Java 模組系統建置應用程式

Gradle 支援建置 Java 模組，如 Java Library 外掛程式文件中的對應區段所述。Java 模組也可以執行，你可以使用 application 外掛程式來執行和封裝此類模組化應用程式。除了對非模組化應用程式執行的動作之外，你還需要執行兩件事。

首先，你需要新增 module-info.java 檔案來描述你的應用程式模組。請參閱 Java Library 外掛程式文件以取得關於此主題的更多詳細資訊。

其次，你需要告訴 Gradle 你想要執行的模組名稱，以及 main 類別名稱，如下所示

範例 5. 設定模組化應用程式的 main 模組

build.gradle.kts

application {
    mainModule = "org.gradle.sample.app" // name defined in module-info.java
    mainClass = "org.gradle.sample.Main"
}

build.gradle

application {
    mainModule = 'org.gradle.sample.app' // name defined in module-info.java
    mainClass = 'org.gradle.sample.Main'
}

這樣就完成了。如果你執行應用程式，透過執行 run 任務或透過產生的啟動指令碼，它將以模組執行，並在執行階段遵循模組邊界。例如，從另一個模組對內部套件的反射存取可能會失敗。

設定的主要類別也會內嵌到應用程式 Jar 的 module-info.class 檔案中。如果你使用 java 指令直接執行模組化應用程式，那麼提供模組名稱就足夠了。

你也可以查看現成的範例，其中包含一個模組化應用程式，作為多專案的一部分。

建立發行版

可以透過發行版外掛程式 (會自動套用) 來建立應用程式的發行版。main 發行版會建立以下內容

表 1. 發行版內容
位置	內容
(根目錄)	`src/dist`
`lib`	所有執行階段相依項和主要來源設定類別檔。
`bin`	啟動指令碼 (由 `startScripts` 任務產生)。

要新增到發行版的靜態檔案可以簡單地新增到 src/dist。更進階的自訂可以透過設定主要發行版公開的 CopySpec 來完成。

範例 6. 在應用程式發行版中包含來自其他任務的輸出

build.gradle.kts

val createDocs by tasks.registering {
    val docs = layout.buildDirectory.dir("docs")
    outputs.dir(docs)
    doLast {
        docs.get().asFile.mkdirs()
        docs.get().file("readme.txt").asFile.writeText("Read me!")
    }
}

distributions {
    main {
        contents {
            from(createDocs) {
                into("docs")
            }
        }
    }
}

build.gradle

tasks.register('createDocs') {
    def docs = layout.buildDirectory.dir('docs')
    outputs.dir docs
    doLast {
        docs.get().asFile.mkdirs()
        docs.get().file('readme.txt').asFile.write('Read me!')
    }
}

distributions {
    main {
        contents {
            from(createDocs) {
                into 'docs'
            }
        }
    }
}

透過指定發行版應該包含任務的輸出檔案 (請參閱增量建置)，Gradle 知道在組建發行版之前必須呼叫產生檔案的任務，並會為你處理這件事。

你可以執行 gradle installDist 來在 build/install/projectName 中建立應用程式的映像。你可以執行 gradle distZip 來建立包含發行版的 ZIP，執行 gradle distTar 來建立應用程式 TAR，或執行 gradle assemble 來建立兩者。

自訂啟動指令碼產生

應用程式外掛程式可以立即產生 Unix (適用於 Linux、macOS 等) 和 Windows 啟動指令碼。啟動指令碼會啟動 JVM，並使用定義為原始建置和執行階段環境一部分 (例如 JAVA_OPTS 環境變數) 的指定設定。預設指令碼範本是根據用於啟動 Gradle 本身的指令碼，這些指令碼會作為 Gradle 發行版的一部分提供。

啟動指令碼完全可自訂。請參閱 CreateStartScripts 的文件，以取得更多詳細資料和自訂範例。

工作

應用程式外掛程式會將下列工作新增到專案。

run — JavaExec: 依賴於：classes

啟動應用程式。
startScripts — CreateStartScripts: 依賴於：jar

建立特定於作業系統的指令碼，以作為 JVM 應用程式執行專案。
installDist — Sync: 依賴於：jar、startScripts

將應用程式安裝到指定的目錄。
distZip — Zip: 依賴於：jar、startScripts

建立完整的發行版 ZIP 檔案，包括執行時期函式庫和特定於作業系統的指令碼。
distTar — Tar: 依賴於：jar、startScripts

建立完整的發行版 TAR 檔案，包括執行時期函式庫和特定於作業系統的指令碼。

應用程式擴充

應用程式外掛程式會將擴充新增到專案，您可以使用它來設定其行為。請參閱 JavaApplication DSL 文件，以取得有關擴充中可用屬性的更多資訊。

您可以透過先前顯示的 application {} 區塊設定擴充，例如在您的建置指令碼中使用下列內容

build.gradle.kts

application {
    executableDir = "custom_bin_dir"
}

build.gradle

application {
    executableDir = 'custom_bin_dir'
}

啟動指令碼授權

為應用程式產生的啟動指令碼在 Apache 2.0 軟體授權下授權。

慣例屬性 (已棄用)

此外掛程式也會將一些慣例屬性新增到專案，您可以使用它們來設定其行為。這些屬性已棄用，並由上述擴充取代。請參閱 Project DSL 文件，以取得有關它們的資訊。

與擴充屬性不同，這些屬性會顯示為建置指令碼中的頂層專案屬性。例如，若要變更應用程式名稱，您只要將下列內容新增到建置指令碼即可

build.gradle.kts

application.applicationName = "my-app"

build.gradle

application.applicationName = 'my-app'

此頁面有幫助嗎？