組建初始化外掛可用於建立新的 Gradle 組建。它支援建立各種類型的全新 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 組建類型

組建初始化外掛支援產生各種組建類型。以下列出這些類型，並可在以下 區段 中取得每個類型的更多詳細資訊。

表格 1. 組建初始化類型
類型 說明

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。

所有建置類型也會在建置中設定 Gradle Wrapper。

建置初始化類型

pom 建置類型 (Maven 轉換)

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

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

轉換流程具有下列功能

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

  • 同時支援單一模組和多模組專案

  • 支援自訂模組名稱 (與目錄名稱不同)

  • 產生一般元資料 - 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 佔用空間。

儘管如此，許多 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 建置。它會建立範例設定和建置檔案，並附有註解和連結以協助開始使用。

當沒有明確指定類型，且無法推論類型時，會使用此類型。