Build Init 外掛程式可用於建立新的 Gradle 建置。它支援建立各種 Brand New Gradle 建置類型，以及將現有的 Apache Maven 建置轉換為 Gradle。

範例用法

gradle init \
  --type java-application \
  --dsl kotlin \
  --test-framework junit-jupiter \
  --package my.project \
  --project-name my-project  \
  --no-split-project  \
  --java-version 17

當選取的專案類型缺少必要參數時，Gradle 會進入互動模式並提示使用者。

支援的 Gradle 建置類型

Build Init 外掛程式支援產生各種建置類型。這些類型列於下方，並在以下章節中提供關於每種類型的更多詳細資訊。

表 1. 建置 init 類型
類型 描述

pom

將現有的 Apache Maven 建置轉換為 Gradle

basic

基礎、空的 Gradle 建置

java-application

以 Java 實作的命令列應用程式

java-gradle-plugin

以 Java 實作的 Gradle 外掛程式

java-library

Java 程式庫

kotlin-application

以 Kotlin/JVM 實作的命令列應用程式

kotlin-gradle-plugin

以 Kotlin/JVM 實作的 Gradle 外掛程式

kotlin-library

Kotlin/JVM 程式庫

groovy-application

以 Groovy 實作的命令列應用程式

groovy-gradle-plugin

以 Groovy 實作的 Gradle 外掛程式

groovy-library

Groovy 程式庫

scala-application

Scala 應用程式

scala-library

Scala 程式庫

cpp-application

以 C++ 實作的命令列應用程式

cpp-library

C++ 程式庫

任務

此外掛程式將以下任務新增至專案

init — InitBuild

產生 Gradle 建置。

Gradle 外掛程式通常需要先套用到專案才能使用（請參閱使用外掛程式）。但是，Build Init 外掛程式會自動套用到每個建置的根專案，這表示您不需要明確套用它即可使用。您可以直接在您想要建立 Gradle 建置的目錄中執行名為 init 的任務。不需要建立「stub」build.gradle 檔案來套用此外掛程式。

要建立什麼

使用 init 任務最簡單且建議的方式是從互動式主控台執行 gradle init。Gradle 將列出可用的建置類型，並要求您選取一種。然後，它會詢問一些額外問題，讓您可以微調結果。

init 任務有幾個命令列選項可用於控制它將產生什麼。當 Gradle 不是從互動式主控台執行時，您可以使用這些選項。您可以使用 help 任務查看可用的選項

gradle help --task init

可以使用 --type 命令列選項指定建置類型。例如，若要建立 Java 程式庫專案，請執行

gradle init --type java-library

如果未提供 --type 選項，Gradle 將嘗試從環境推斷類型。例如，如果找到要轉換為 Gradle 建置的 pom.xml 檔案，它將推斷類型為「pom」。如果無法推斷類型，將使用類型「basic」。

init 任務也支援使用 Gradle Kotlin DSL 或 Gradle Groovy DSL 產生建置腳本。建置腳本 DSL 預設為大多數建置類型的 Kotlin DSL，以及 Groovy 建置類型的 Groovy DSL。可以使用 --dsl 命令列選項選取 DSL。

例如，若要建立具有 Kotlin DSL 建置腳本的 Java 程式庫專案，請執行

gradle init --type java-library --dsl kotlin

您可以使用 --project-name 選項變更產生的專案名稱。預設為執行 init 任務的目錄名稱。

您可以使用 --package 選項變更用於產生原始碼檔案的套件。預設為專案名稱。

如果提供了 --incubating 選項，Gradle 將產生可能使用最新版本 API 的建置腳本，這些 API 標記為 @Incubating 且仍可能變更。若要停用此行為，請使用 --no-incubating。

如果提供了 --overwrite 選項，Gradle 將覆寫執行 init 任務的目錄中的任何現有檔案。預設情況下，如果 Gradle 在目錄中找到任何檔案，init 將提示使用者繼續。

所有建置類型也都設定了建置中的 Gradle Wrapper。

選項

選項 描述 範例

--comments / --no-comments

在檔案中包含說明性註解。使用者也可以使用屬性 org.gradle.buildinit.comments。

--incubating

允許產生的建置使用新功能和 API。

--use-defaults / --no-use-defaults

對未明確配置的選項使用預設值。

--overwrite

允許覆寫建置目錄中的現有檔案。

--split-project / --no-split-project

將功能分散到多個子專案中？

--java-version

提供專案中要使用的 Java 版本。

11

--insecure-protocol

如何處理用於 Maven 儲存庫的不安全 URL。

fail

--type

設定要產生的專案類型。

java-application

--dsl

設定要在產生的腳本中使用的建置腳本 DSL。

groovy

--test-framework

設定要使用的測試框架。

junit-jupiter

--project-name

設定專案名稱。預設為目錄名稱。

my-project

--package

設定原始碼檔案的套件。

my.project

建置 init 類型

pom 建置類型 (Maven 轉換)

「pom」類型可用於將 Apache Maven 建置轉換為 Gradle 建置。這透過將 POM 轉換為一個或多個 Gradle 檔案來運作。只有在調用 init 任務的目錄中，或透過「-p」命令列選項調用時，在指定的專案目錄中存在有效的「pom.xml」檔案時，才能使用此類型。如果存在此類檔案，將自動推斷此「pom」類型。

Maven 轉換實作的靈感來自最初由 Gradle 社群成員開發的 maven2gradle 工具。

轉換過程具有以下功能

  • 使用有效的 POM 和有效設定（支援 POM 繼承、相依性管理、屬性）

  • 支援單模組和多模組專案

  • 支援自訂模組名稱（與目錄名稱不同）

  • 產生一般 metadata - id、描述和版本

  • 套用 Maven Publish、Java Library 和 War 外掛程式（視需要）

  • 如果需要，支援將 war 專案封裝為 jar

  • 產生相依性（包括外部和模組間）

  • 產生下載儲存庫（包括本機 Maven 儲存庫）

  • 調整 Java 編譯器設定

  • 支援封裝原始碼、測試和 javadoc

  • 支援 TestNG 執行器

  • 從 Maven Enforcer 外掛程式設定產生全域排除項

  • 提供 處理位於使用 http 的 URL 的 Maven 儲存庫的選項

--insecure-protocol 選項

此選項用於告知轉換過程如何處理轉換位於不安全 http URL 的 Maven 儲存庫。不安全儲存庫設定 --insecure-protocol 選項。預設值為 warn。

可用值為

  • fail - 遇到不安全儲存庫 URL 時立即中止建置。

  • allow - 自動將產生的 Gradle 建置腳本中 Maven 儲存庫 URL 的 allowInsecureProtocol 屬性設定為 true。

  • warn - 發出關於每個不安全 URL 的警告。產生註解掉的行以啟用每個儲存庫，如 allow 選項所示。您必須選擇加入，方法是編輯產生的腳本並取消註解每個儲存庫 URL，否則 Gradle 建置將會失敗。

  • upgrade - 自動將 http URL 轉換為 https URL。

編譯時期相依性

Maven 使用其隱含的 compile 範圍自動向該專案的消費者公開相依性。此行為是不理想的，Gradle 採取步驟來協助程式庫作者使用 java-library 外掛程式的 api 和 implementation 配置來減少其 API footprint。

儘管如此，許多 Maven 專案都依賴於這種洩漏行為。因此，init 任務會將 compile 範圍的相依性對應到產生的 Gradle 建置腳本中的 api 配置。產生的 Gradle 專案的相依性將最接近現有 Maven 專案的公開相依性；但是，在轉換為 Gradle 後，我們強烈建議盡可能將更多 api 相依性移至 implementation 配置。這有幾個好處

  • 程式庫可維護性 - 透過向消費者公開更少的傳遞相依性，程式庫維護者可以新增或移除相依性，而無需擔心對消費者造成編譯時期中斷。

  • 消費者的相依性衛生 - 在程式庫中使用 implementation 配置可防止其消費者在編譯時期隱含地依賴程式庫的傳遞相依性，這被認為是不良做法。

  • 增加編譯避免 - 減少從專案洩漏的傳遞相依性數量也降低了 ABI 變更將觸發消費者重新編譯的可能性。Gradle 也將花費更少的時間為其最新檢查索引相依性。

  • 編譯速度提升 - 減少從專案洩漏的傳遞相依性數量有助於其消費者的編譯器程序，因為需要類別載入的程式庫更少，Gradle 增量編譯器要追蹤的命名空間也更少。

請參閱 API 和實作分離 和 編譯避免 章節以取得更多資訊。

java-application 建置類型

「java-application」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「application」外掛程式來產生以 Java 實作的命令列應用程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 JUnit 4 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例類別和單元測試

可以透過提供 --test-framework 引數值來指定替代測試框架。若要使用不同的測試框架，請執行以下命令之一

  • gradle init --type java-application --test-framework junit-jupiter：使用 JUnit Jupiter 進行測試，而不是 JUnit 4

  • gradle init --type java-application --test-framework spock：使用 Spock 進行測試，而不是 JUnit 4

  • gradle init --type java-application --test-framework testng：使用 TestNG 進行測試，而不是 JUnit 4

--java-version 選項

建立 Java 專案時，您必須設定 Java 版本。您可以透過提供您想要使用的 Java 主要版本來做到這一點

gradle init --type java-application  --java-version 11 --dsl kotlin # and other parameters

java-library 建置類型

「java-library」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「java」外掛程式來產生以 Java 實作的程式庫

  • 使用「mavenCentral」相依性儲存庫

  • 使用 JUnit 4 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例類別和單元測試

可以透過提供 --test-framework 引數值來指定替代測試框架。若要使用不同的測試框架，請執行以下命令之一

  • gradle init --type java-library --test-framework junit-jupiter：使用 JUnit Jupiter 進行測試，而不是 JUnit 4

  • gradle init --type java-library --test-framework spock：使用 Spock 進行測試，而不是 JUnit 4

  • gradle init --type java-library --test-framework testng：使用 TestNG 進行測試，而不是 JUnit 4

java-gradle-plugin 建置類型

「java-gradle-plugin」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「java-gradle-plugin」外掛程式來產生以 Java 實作的 Gradle 外掛程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 JUnit 4 和 TestKit 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例類別和單元測試

kotlin-application 建置類型

「kotlin-application」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「org.jetbrains.kotlin.jvm」和「application」外掛程式來產生以 Kotlin 實作的命令列應用程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Kotlin 1.x

  • 使用 Kotlin 測試程式庫 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Kotlin 類別和關聯的 Kotlin 測試類別

kotlin-library 建置類型

「kotlin-library」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「org.jetbrains.kotlin.jvm」外掛程式來產生以 Kotlin 實作的程式庫

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Kotlin 1.x

  • 使用 Kotlin 測試程式庫 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Kotlin 類別和關聯的 Kotlin 測試類別

kotlin-gradle-plugin 建置類型

「kotlin-gradle-plugin」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「java-gradle-plugin」和「org.jetbrains.kotlin.jvm」外掛程式來產生以 Kotlin 實作的 Gradle 外掛程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Kotlin 1.x

  • 使用 Kotlin 測試程式庫 和 TestKit 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例類別和單元測試

scala-application 建置類型

「scala-application」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「scala」外掛程式來產生以 Scala 實作的應用程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Scala 2.13

  • 使用 ScalaTest 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Scala 類別和關聯的 ScalaTest 測試套件

scala-library 建置類型

「scala-library」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「scala」外掛程式來產生以 Scala 實作的程式庫

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Scala 2.13

  • 使用 ScalaTest 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Scala 類別和關聯的 ScalaTest 測試套件

groovy-library 建置類型

「groovy-library」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「groovy」外掛程式來產生以 Groovy 實作的程式庫

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Groovy 2.x

  • 使用 Spock 測試框架 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Groovy 類別和關聯的 Spock 規格

groovy-application 建置類型

「groovy-application」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「application」和「groovy」外掛程式來產生以 Groovy 實作的命令列應用程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Groovy 2.x

  • 使用 Spock 測試框架 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 Groovy 類別和關聯的 Spock 規格

groovy-gradle-plugin 建置類型

「groovy-gradle-plugin」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「java-gradle-plugin」和「groovy」外掛程式來產生以 Groovy 實作的 Gradle 外掛程式

  • 使用「mavenCentral」相依性儲存庫

  • 使用 Groovy 2.x

  • 使用 Spock 測試框架 和 TestKit 進行測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例類別和單元測試

cpp-application 建置類型

「cpp-application」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「cpp-application」外掛程式來產生以 C++ 實作的命令列應用程式

  • 使用「cpp-unit-test」外掛程式來建置和執行簡單的單元測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 C++ 類別、私有標頭檔和關聯的測試類別

cpp-library 建置類型

「cpp-library」建置類型無法推斷。必須明確指定。

它具有以下功能

  • 使用「cpp-library」外掛程式來產生 C++ 程式庫

  • 使用「cpp-unit-test」外掛程式來建置和執行簡單的單元測試

  • 在傳統位置中具有原始碼的目錄

  • 如果沒有現有的原始碼或測試檔案，則包含範例 C++ 類別、公用標頭檔和關聯的測試類別

basic 建置類型

「basic」建置類型適用於建立新的 Gradle 建置。它會建立範例設定和建置檔案，並附帶註解和連結以協助您入門。

當未明確指定類型，且無法推斷類型時，會使用此類型。