Gradle 正在持续开发中。新版本会定期且频繁地发布(大约每六周一次),如关于生命周期结束支持的部分所述。
持续改进与频繁发布相结合,使得新特性能够尽早提供给用户。早期用户提供了宝贵的反馈,这些反馈会被纳入开发过程。
定期向用户提供新功能是 Gradle 平台的核心价值之一。
同时,API 和特性的稳定性也被非常重视,并被视为 Gradle 平台的核心价值。设计选择和自动化测试被纳入开发流程中,并通过关于向后兼容性的部分予以规范。
Gradle 的特性生命周期旨在实现这些目标。它还向 Gradle 用户传达特性的状态。在此上下文中,术语特性通常指代 API 或 DSL 方法或属性,但其定义不限于此。命令行参数和执行模式(例如构建守护进程)是其他特性类型的两个示例。
1. 内部
内部特性并非为公共使用而设计,仅供 Gradle 自身使用。它们可能随时以任何方式更改,恕不另行通知。因此,我们建议避免使用此类特性。内部特性没有文档。如果它出现在本用户手册、DSL 参考或 API 参考中,那么该特性就不是内部的。
内部特性可能会演变为公开特性。
2. 孵化中
特性在引入时处于孵化中状态,以便在公开之前能够将真实世界的反馈纳入其中。这也让愿意测试未来潜在更改的用户能够提前访问。
处于孵化中状态的特性在未来的 Gradle 版本中可能会发生变化,直到它不再处于孵化中状态。Gradle 版本中对孵化中特性的更改将在该版本的发布说明中重点说明。新特性的孵化期根据特性的范围、复杂性和性质而异。
处于孵化中状态的特性会被标记出来。在源代码中,所有处于孵化中状态的方法/属性/类都用 incubating 进行注解。这导致它们在 DSL 和 API 参考中有一个特殊标记。
如果本用户手册中讨论了处于孵化中的特性,会明确说明其处于孵化中状态。
特性预览 API
特性预览 API 允许通过在您的 settings 文件中添加 enableFeaturePreview('FEATURE')
来激活某些孵化中的特性。具体的预览特性将在发布说明中公布。
当孵化中的特性被提升为公开或被移除时,它们的特性预览标志将变得过时,不再有任何效果,应从 settings 文件中移除。
3. 公开
非内部特性的默认状态是公开。用户手册、DSL 参考或 API 参考中记录的任何未明确说明为孵化中或已废弃的内容都被视为公开。特性被称为从孵化中状态被提升到公开状态。每个版本的发布说明会指出哪些先前处于孵化中的特性在该版本中被提升为公开。
公开特性在没有经过废弃流程的情况下永远不会被移除或有意更改。所有公开特性都受向后兼容性政策约束。
4. 已废弃
由于 Gradle 的自然演进,某些特性可能会被替换或变得无关紧要。此类特性在被废弃后最终将从 Gradle 中移除。已废弃的特性可能会在最终根据向后兼容性政策被移除之前变得过时。
已废弃的特性会被标记出来。在源代码中,所有已废弃的方法/属性/类都用“@java.lang.Deprecated”注解,这反映在 DSL 和 API 参考中。在大多数情况下,已废弃的元素都有替代方案,文档中会对此进行说明。使用已废弃的特性会在 Gradle 的输出中产生运行时警告。
应避免使用已废弃的特性。每个版本的发布说明会指出该版本中任何被废弃的特性。
向后兼容性政策
Gradle 在主要版本之间提供向后兼容性(例如,1.x
、2.x
等)。一旦公开特性在某个 Gradle 版本中引入,它将无限期保留,除非被废弃。一旦废弃,它可能会在下一个主要版本中移除。已废弃的特性可能跨主要版本得到支持,但这不保证。
发布生命周期结束政策
每天都会创建一个新的 Gradle 每夜构建。
这包含了当天通过 Gradle 大量的持续集成测试所做的所有更改。每夜构建可能包含新的更改,这些更改可能稳定,也可能不稳定。
Gradle 团队为每个次要或主要版本创建一个称为发布候选 (RC) 的预发布分发版本。在短时间(通常一周)未发现问题后,发布候选版本会被提升为正式发布 (GA) 版本。如果在发布候选版本中发现回归问题,将创建一个新的 RC 分发版本,并重复此过程。发布候选版本在发布窗口期内受到支持,但不适用于生产环境。在 RC 阶段,非常感谢提交错误报告。
Gradle 团队可能会由于关键错误修复或回归问题而创建额外的补丁发布版本来替换最终发布版本。例如,Gradle 5.2.1 替换了 Gradle 5.2 版本。
一旦发布候选版本发布,所有特性开发都将转移到最新主要版本的下一个版本。因此,每个 Gradle 次要版本发布都会导致同一主要版本中的先前次要版本达到生命周期结束 (EOL)。EOL 版本不会收到错误修复或特性回溯。
对于主要版本,Gradle 会将关键修复和安全修复回溯到上一个主要版本中的最后一个次要版本。例如,当 Gradle 7 是最新的主要版本时,在 6.x 系列中发布了多个版本,包括 Gradle 6.9(以及后续版本)。
因此,每个 Gradle 主要版本发布会导致
-
上一个主要版本仅进入维护阶段。它将仅接收关键错误修复和安全修复。
-
上上一个主要版本达到生命周期结束 (EOL),并且该发布系列将不再接收任何新的修复。
公开的 Gradle API
Gradle 提供了许多公开的 API,允许开发人员与各种构建系统组件交互。
任何包含 Internal
的类名,或位于包含 .internal.
段的包中的类,根据定义都不是公开 Gradle API 的一部分,不应依赖它们来实现稳定使用。
下表总结了公开的 Gradle API 及其常见用例。这不是一个详尽的列表
API 包 | 描述 | 常见用例 |
---|---|---|
|
核心 Gradle API |
- 定义关键接口,如 |
|
认证 API |
- 处理仓库和服务的认证 |
|
构建生命周期 API |
- 管理构建阶段和执行 |
|
构建初始化 API |
- 用于生成新的 Gradle 项目 |
|
构建缓存 API |
- 提供存储和重用构建输出的机制 |
|
并发执行 API |
- 管理并行任务执行 |
|
部署 API |
- 支持管理和自动化应用程序部署 |
|
环境配置 API |
- 提供对环境变量和设置的访问 |
|
Javadoc API |
- 为外部依赖生成 Javadoc |
|
IDE 集成 API |
- 管理 Gradle 对 IntelliJ 和 Eclipse 等 IDE 的支持 |
|
复合构建 API |
- 支持跨多个 Gradle 构建进行依赖管理 |
|
Ivy 依赖管理 API |
- 支持 Ivy 仓库和依赖解析 |
|
Java 虚拟机 API |
- 管理基于 JVM 的构建 |
|
语言插件 API |
- 定义 Gradle 对多种语言(Java、Kotlin 等)的支持 |
|
Maven 依赖管理 API |
- 支持 Maven 仓库和依赖解析 |
|
原生平台 API |
- 提供对 C、C++ 和其他原生构建的支持 |
|
输入规范化 API |
- 通过定义输入规范化规则帮助优化缓存 |
|
平台依赖管理 API |
- 定义和管理平台的依赖约束 |
|
Play Framework 支持 API |
- 为 Play Framework 项目提供支持 |
|
插件开发 API |
- 支持编写和发布自定义 Gradle 插件 |
|
插件仓库 API |
- 定义 Gradle 插件的仓库 |
|
插件应用 API |
- 处理构建脚本中的插件应用 |
|
插件管理 API |
- 为 Gradle 插件提供集中管理 |
|
内置插件 API |
- 包括 Gradle 的内置插件(Java、Kotlin 等) |
|
进程管理 API |
- 允许从 Gradle 任务运行外部进程 |
|
测试夹具 API |
- 为 Gradle 插件开发者提供测试工具 |
|
JaCoCo 测试覆盖率 API |
- 与 JaCoCo 集成以获取代码覆盖率报告 |
|
Tooling API ( |
- 允许外部应用程序与 Gradle 交互 |
|
Swift 包管理器 API |
- 提供 Gradle 与 Swift 包管理器的集成 |
|
基于模型规则的 API |
- 使用模型配置 Gradle 构建的遗留 API |
|
Gradle TestKit API |
- 提供用于测试 Gradle 插件的工具 |
|
测试框架 API |
- 为 Gradle 构建定义测试框架 |
|
版本控制系统 API |
- 允许从 VCS (Git, SVN) 获取依赖 |
|
工作执行 API |
- 提供并行和增量任务执行的工具 |
|
Worker API |
- 支持 Gradle 任务的并行执行 |
|
实用工具 API |
- 提供 Gradle 内部使用的各种实用函数 |