构建初始化插件 - Gradle 构建系统

构建初始化插件可用于创建新的 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`

--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 转换的实现灵感来自 maven2gradle 工具，该工具最初由 Gradle 社区成员开发。

转换过程具有以下特性

使用有效的 POM 和有效的 settings（支持 POM 继承、依赖项管理、properties）
支持单模块和多模块项目
支持自定义模块名称（与目录名称不同）
生成通用元数据 - id、description 和 version
应用 Maven Publish、Java Library 和 War 插件（根据需要）
如果需要，支持将 war 项目打包为 jars
生成依赖项（外部依赖项和模块间依赖项）
生成下载仓库（包括本地 Maven 仓库）
调整 Java 编译器设置
支持打包 sources、tests 和 javadocs
支持 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 和 implementation 分离以及编译避免部分。

`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