构建初始化插件可用于创建新的 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 将尝试从环境中推断类型。例如，如果找到要转换为 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 选项

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

可用值包括

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

  • allow - 自动将 allowInsecureProtocol 属性设置为 true，用于生成的 Gradle 构建脚本中的 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 构建很有用。它创建示例设置和构建文件，其中包含注释和链接以帮助入门。

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