构建初始化插件可用于创建新的 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的任务。无需创建“存根”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

构建初始化类型

pom构建类型（Maven 转换）

“pom”类型可用于将 Apache Maven 构建转换为 Gradle 构建。这通过将 POM 转换为一个或多个 Gradle 文件来实现。它只能在调用init任务的目录中存在有效的“pom.xml”文件时使用，或者，如果通过“-p”命令行选项调用，则在指定的项目目录中。如果存在这样的文件，此“pom”类型将自动推断。

Maven 转换实现受到 Gradle 社区成员最初开发的maven2gradle 工具的启发。

转换过程具有以下特性

  • 使用有效的 POM 和有效设置（支持 POM 继承、依赖管理、属性）

  • 支持单模块和多模块项目

  • 支持自定义模块名称（与目录名称不同）

  • 生成通用元数据 - id、描述和版本

  • 应用Maven Publish、Java Library和War插件（根据需要）

  • 如果需要，支持将 war 项目打包为 jar

  • 生成依赖项（包括外部和模块间）

  • 生成下载仓库（包括本地 Maven 仓库）

  • 调整 Java 编译器设置

  • 支持源代码、测试和 javadoc 的打包

  • 支持 TestNG 运行器

  • 从 Maven enforcer 插件设置生成全局排除项

  • 提供了处理使用http的 URL 上的 Maven 仓库的选项

--insecure-protocol选项

此选项用于告诉转换过程如何处理转换位于不安全的httpURL 上的 Maven 仓库。不安全的仓库设置--insecure-protocol选项。默认值为warn。

可用值有

  • fail - 遇到不安全的仓库 URL 时立即中止构建。

  • allow - 在生成的 Gradle 构建脚本中自动将 Maven 仓库 URL 的allowInsecureProtocol属性设置为true。

  • warn - 对每个不安全的 URL 发出警告。生成注释掉的行以启用每个仓库，如allow选项所述。您必须通过编辑生成的脚本并取消注释每个仓库 URL 来选择启用，否则 Gradle 构建将失败。

  • upgrade - 自动将httpURL 转换为httpsURL。

编译时依赖

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 构建非常有用。它会创建示例设置和构建文件，其中包含注释和链接，以帮助您入门。

当未显式指定任何类型且无法推断任何类型时，将使用此类型。