构建初始化插件可用于创建新的 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 插件通常需要在使用之前应用到项目（参见 使用插件）。但是，构建初始化插件会自动应用于每个构建的根项目，这意味着您无需显式应用它即可使用它。您只需在要创建 Gradle 构建的目录中执行名为 init 的任务即可。无需创建“存根”build.gradle 文件来应用插件。

要创建的内容

使用 init 任务的最简单也是最推荐的方式是从交互式控制台运行 gradle init。Gradle 将列出可用的构建类型并要求您选择一个。然后它会提出一些其他问题，以便您可以微调结果。

init 任务有几个可用于控制它将生成内容的命令行选项。当 Gradle 不是从交互式控制台运行时，您可以使用这些选项。您可以使用 help 任务查看可用的选项

gradle help --task init

可以使用 --type 命令行选项指定构建类型。例如，要创建一个 Java 库项目，请运行

gradle init --type java-library

如果没有提供 --type 选项，Gradle 将尝试从环境中推断类型。例如，如果它找到一个 pom.xml 文件要转换为 Gradle 构建，它将推断出“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 发布、Java 库 和 War 插件（根据需要）

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

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

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

  • 调整 Java 编译器设置

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

  • 支持 TestNG 运行器

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

  • 提供 用于处理位于使用 `http` 的 URL 的 Maven 存储库的选项

`--insecure-protocol` 选项

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

可用值是

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

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

  • 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 构建。它创建示例设置和构建文件，并带有注释和链接以帮助入门。

当没有显式指定类型，并且无法推断类型时，将使用此类型。