实现二进制插件
二进制插件是指编译为 JAR 文件并以 JAR 文件形式分发的插件。这些插件通常用 Java 或 Kotlin 编写,并为 Gradle 构建提供自定义功能或任务。
使用插件开发插件
Gradle 插件开发插件可用于帮助开发 Gradle 插件。
要应用和配置插件,请将以下代码添加到构建文件中
plugins {
`java-gradle-plugin`
}
gradlePlugin {
plugins {
create("simplePlugin") {
id = "org.example.greeting"
implementationClass = "org.example.GreetingPlugin"
}
}
}
plugins {
id 'java-gradle-plugin'
}
gradlePlugin {
plugins {
simplePlugin {
id = 'org.example.greeting'
implementationClass = 'org.example.GreetingPlugin'
}
}
}
创建插件 ID
插件 ID 旨在全局唯一,类似于 Java 包名称(即反向域名)。此格式有助于防止命名冲突,并允许对具有相似所有权的插件进行分组。
明确的插件标识符简化了将插件应用到项目。插件 ID 应结合反映命名空间(指向您或您的组织的合理指针)和它提供的插件名称的组件。例如,如果您的 Github 帐户名为 foo
,您的插件名为 bar
,则合适的插件 ID 可能为 com.github.foo.bar
。类似地,如果该插件是在 baz
组织中开发的,则插件 ID 可能为 org.baz.bar
。
插件 ID 应遵守以下准则
-
可以包含任何字母数字字符、“.” 和 “-”。
-
必须至少包含一个 “.” 字符,以将命名空间与插件的名称分隔开。
-
惯例上对命名空间使用小写反向域名约定。
-
惯例上在名称中仅使用小写字符。
-
不得使用
org.gradle
、com.gradle
和com.gradleware
命名空间。 -
不能以 “.” 字符开头或结尾。
-
不能包含连续的 “.” 字符(即 “..”)。
标识所有权和名称的命名空间足以作为插件 ID。
在单个 JAR 工件中捆绑多个插件时,建议遵循相同的命名约定。此做法有助于将相关的插件逻辑分组。
在单个项目中可以定义和注册的插件数量没有限制(由不同的标识符)。
作为类编写的插件的标识符应在包含插件类的项目的构建脚本中定义。为此,需要应用 java-gradle-plugin
plugins {
id("java-gradle-plugin")
}
gradlePlugin {
plugins {
create("androidApplicationPlugin") {
id = "com.android.application"
implementationClass = "com.android.AndroidApplicationPlugin"
}
create("androidLibraryPlugin") {
id = "com.android.library"
implementationClass = "com.android.AndroidLibraryPlugin"
}
}
}
plugins {
id 'java-gradle-plugin'
}
gradlePlugin {
plugins {
androidApplicationPlugin {
id = 'com.android.application'
implementationClass = 'com.android.AndroidApplicationPlugin'
}
androidLibraryPlugin {
id = 'com.android.library'
implementationClass = 'com.android.AndroidLibraryPlugin'
}
}
}
使用文件
在开发插件时,最好在接受文件位置的输入配置时保持灵活性。
建议使用 Gradle 的 托管属性 和 project.layout
来选择文件或目录位置。这将启用延迟配置,以便仅在需要文件时才解析实际位置,并且可以在构建配置期间随时重新配置。
此 Gradle 构建文件定义了一个任务 GreetingToFileTask
,用于向文件写入问候语。它还注册了两个任务:greet
,用于创建包含问候语的文件,和 sayGreeting
,用于打印文件内容。greetingFile
属性用于指定问候语的文件路径
abstract class GreetingToFileTask : DefaultTask() {
@get:OutputFile
abstract val destination: RegularFileProperty
@TaskAction
fun greet() {
val file = destination.get().asFile
file.parentFile.mkdirs()
file.writeText("Hello!")
}
}
val greetingFile = objects.fileProperty()
tasks.register<GreetingToFileTask>("greet") {
destination = greetingFile
}
tasks.register("sayGreeting") {
dependsOn("greet")
val greetingFile = greetingFile
doLast {
val file = greetingFile.get().asFile
println("${file.readText()} (file: ${file.name})")
}
}
greetingFile = layout.buildDirectory.file("hello.txt")
abstract class GreetingToFileTask extends DefaultTask {
@OutputFile
abstract RegularFileProperty getDestination()
@TaskAction
def greet() {
def file = getDestination().get().asFile
file.parentFile.mkdirs()
file.write 'Hello!'
}
}
def greetingFile = objects.fileProperty()
tasks.register('greet', GreetingToFileTask) {
destination = greetingFile
}
tasks.register('sayGreeting') {
dependsOn greet
doLast {
def file = greetingFile.get().asFile
println "${file.text} (file: ${file.name})"
}
}
greetingFile = layout.buildDirectory.file('hello.txt')
$ gradle -q sayGreeting Hello! (file: hello.txt)
在此示例中,我们将 greet
任务的 destination
属性配置为一个闭包/提供程序,它使用 Project.file(java.lang.Object) 方法进行评估,以便在最后一刻将闭包/提供程序的返回值转换为 File
对象。请注意,我们在任务配置之后指定 greetingFile
属性值。这种惰性评估是接受任何值(在设置文件属性时)然后在读取属性时解析该值的优势所在。
您可以在 使用文件 中了解有关惰性使用文件的更多信息。
使用扩展使插件可配置
大多数插件都为构建脚本和其他插件提供配置选项,以便自定义插件的工作方式。插件使用扩展对象来实现此目的。
Project 具有关联的 ExtensionContainer 对象,该对象包含已应用于项目的插件的所有设置和属性。您可以通过向此容器添加扩展对象来为插件提供配置。
扩展对象只是一个具有表示配置的 Java Bean 属性的对象。
让我们向项目添加一个 greeting
扩展对象,它允许您配置问候语
interface GreetingPluginExtension {
val message: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Add the 'greeting' extension object
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
// Add a task that uses configuration from the extension object
project.task("hello") {
doLast {
println(extension.message.get())
}
}
}
}
apply<GreetingPlugin>()
// Configure the extension
the<GreetingPluginExtension>().message = "Hi from Gradle"
interface GreetingPluginExtension {
Property<String> getMessage()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
// Add the 'greeting' extension object
def extension = project.extensions.create('greeting', GreetingPluginExtension)
// Add a task that uses configuration from the extension object
project.task('hello') {
doLast {
println extension.message.get()
}
}
}
}
apply plugin: GreetingPlugin
// Configure the extension
greeting.message = 'Hi from Gradle'
$ gradle -q hello Hi from Gradle
在此示例中,GreetingPluginExtension
是一个具有名为 message
的属性的对象。扩展对象以 greeting
名称添加到项目。此对象作为与扩展对象同名的项目属性变为可用。the<GreetingPluginExtension>()
等效于 project.extensions.getByType(GreetingPluginExtension::class.java)
。
通常,您需要在单个插件上指定几个相关属性。Gradle 为每个扩展对象添加一个配置块,以便您可以对设置进行分组
interface GreetingPluginExtension {
val message: Property<String>
val greeter: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
project.task("hello") {
doLast {
println("${extension.message.get()} from ${extension.greeter.get()}")
}
}
}
}
apply<GreetingPlugin>()
// Configure the extension using a DSL block
configure<GreetingPluginExtension> {
message = "Hi"
greeter = "Gradle"
}
interface GreetingPluginExtension {
Property<String> getMessage()
Property<String> getGreeter()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
def extension = project.extensions.create('greeting', GreetingPluginExtension)
project.task('hello') {
doLast {
println "${extension.message.get()} from ${extension.greeter.get()}"
}
}
}
}
apply plugin: GreetingPlugin
// Configure the extension using a DSL block
greeting {
message = 'Hi'
greeter = 'Gradle'
}
$ gradle -q hello Hi from Gradle
在此示例中,可以在 configure<GreetingPluginExtension>
块中对多个设置进行分组。configure
函数用于配置扩展对象。它提供了一种便捷的方式来设置属性或将配置应用于这些对象。在构建脚本的 configure
函数中使用的类型(GreetingPluginExtension
)必须与扩展类型匹配。然后,在执行该块时,该块的接收器就是扩展。
在此示例中,可以在 greeting
闭包中对多个设置进行分组。构建脚本中闭包块的名称(greeting
)必须与扩展对象名称匹配。然后,在执行该闭包时,扩展对象上的字段将基于标准 Groovy 闭包委托功能映射到闭包中的变量。
声明 DSL 配置容器
使用扩展对象扩展 Gradle DSL,为插件添加项目属性和 DSL 块。由于扩展对象是一个常规对象,因此可以通过向扩展对象添加属性和方法,在插件块内提供您自己的 DSL。
让我们考虑以下构建脚本以作说明。
plugins {
id("org.myorg.server-env")
}
environments {
create("dev") {
url = "https://127.0.0.1:8080"
}
create("staging") {
url = "http://staging.enterprise.com"
}
create("production") {
url = "http://prod.enterprise.com"
}
}
plugins {
id 'org.myorg.server-env'
}
environments {
dev {
url = 'https://127.0.0.1:8080'
}
staging {
url = 'http://staging.enterprise.com'
}
production {
url = 'http://prod.enterprise.com'
}
}
插件公开的 DSL 公开了一个容器,用于定义一组环境。用户配置的每个环境都有一个任意但声明性的名称,并用它自己的 DSL 配置块表示。上面的示例实例化了一个开发、暂存和生产环境,包括它各自的 URL。
每个环境都必须在代码中具有数据表示,以捕获这些值。环境的名称是不可变的,可以作为构造函数参数传入。目前,数据对象存储的唯一其他参数是 URL。
以下 ServerEnvironment
对象满足这些要求
abstract public class ServerEnvironment {
private final String name;
@javax.inject.Inject
public ServerEnvironment(String name) {
this.name = name;
}
public String getName() {
return name;
}
abstract public Property<String> getUrl();
}
Gradle 公开了工厂方法 ObjectFactory.domainObjectContainer(Class, NamedDomainObjectFactory),用于创建数据对象的容器。该方法采用的参数是表示数据的类。可以通过将类型为 NamedDomainObjectContainer 的创建实例添加到具有特定名称的扩展容器中,将其公开给最终用户。
插件在插件实现中对捕获的值进行后处理很常见,例如配置任务
public class ServerEnvironmentPlugin implements Plugin<Project> {
@Override
public void apply(final Project project) {
ObjectFactory objects = project.getObjects();
NamedDomainObjectContainer<ServerEnvironment> serverEnvironmentContainer =
objects.domainObjectContainer(ServerEnvironment.class, name -> objects.newInstance(ServerEnvironment.class, name));
project.getExtensions().add("environments", serverEnvironmentContainer);
serverEnvironmentContainer.all(serverEnvironment -> {
String env = serverEnvironment.getName();
String capitalizedServerEnv = env.substring(0, 1).toUpperCase() + env.substring(1);
String taskName = "deployTo" + capitalizedServerEnv;
project.getTasks().register(taskName, Deploy.class, task -> task.getUrl().set(serverEnvironment.getUrl()));
});
}
}
在上面的示例中,为每个用户配置的环境动态创建部署任务。
您可以在开发自定义 Gradle 类型中找到有关实现项目扩展的更多信息。
建模类似 DSL 的 API
插件公开的 DSL 应该是可读且易于理解的。
例如,让我们考虑插件提供的以下扩展。在其当前形式中,它提供了一个用于配置网站创建的“扁平”属性列表
plugins {
id("org.myorg.site")
}
site {
outputDir = layout.buildDirectory.file("mysite")
websiteUrl = "https://gradle.org.cn"
vcsUrl = "https://github.com/gradle/gradle-site-plugin"
}
plugins {
id 'org.myorg.site'
}
site {
outputDir = layout.buildDirectory.file("mysite")
websiteUrl = 'https://gradle.org.cn'
vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
}
随着公开属性数量的增加,您应该引入嵌套的、更具表现力的结构。
以下代码段添加了一个名为 customData
的新配置块作为扩展的一部分。这提供了这些属性的含义的更强指示
plugins {
id("org.myorg.site")
}
site {
outputDir = layout.buildDirectory.file("mysite")
customData {
websiteUrl = "https://gradle.org.cn"
vcsUrl = "https://github.com/gradle/gradle-site-plugin"
}
}
plugins {
id 'org.myorg.site'
}
site {
outputDir = layout.buildDirectory.file("mysite")
customData {
websiteUrl = 'https://gradle.org.cn'
vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
}
}
实现此类扩展的后备对象很简单。首先,引入一个新的数据对象来管理属性 websiteUrl
和 vcsUrl
abstract public class CustomData {
abstract public Property<String> getWebsiteUrl();
abstract public Property<String> getVcsUrl();
}
在扩展中,创建一个 CustomData
类的实例和一个方法,将捕获的值委托给数据实例。
要配置基础数据对象,请定义类型为 Action 的参数。
以下示例演示了在扩展定义中使用 Action
abstract public class SiteExtension {
abstract public RegularFileProperty getOutputDir();
@Nested
abstract public CustomData getCustomData();
public void customData(Action<? super CustomData> action) {
action.execute(getCustomData());
}
}
将扩展属性映射到任务属性
插件通常使用扩展从构建脚本中捕获用户输入,并将其映射到自定义任务的输入/输出属性。构建脚本作者与扩展的 DSL 交互,而插件实现处理底层逻辑
// Extension class to capture user input
class MyExtension {
@Input
var inputParameter: String? = null
}
// Custom task that uses the input from the extension
class MyCustomTask : org.gradle.api.DefaultTask() {
@Input
var inputParameter: String? = null
@TaskAction
fun executeTask() {
println("Input parameter: $inputParameter")
}
}
// Plugin class that configures the extension and task
class MyPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Create and configure the extension
val extension = project.extensions.create("myExtension", MyExtension::class.java)
// Create and configure the custom task
project.tasks.register("myTask", MyCustomTask::class.java) {
group = "custom"
inputParameter = extension.inputParameter
}
}
}
// Extension class to capture user input
class MyExtension {
@Input
String inputParameter = null
}
// Custom task that uses the input from the extension
class MyCustomTask extends DefaultTask {
@Input
String inputParameter = null
@TaskAction
def executeTask() {
println("Input parameter: $inputParameter")
}
}
// Plugin class that configures the extension and task
class MyPlugin implements Plugin<Project> {
void apply(Project project) {
// Create and configure the extension
def extension = project.extensions.create("myExtension", MyExtension)
// Create and configure the custom task
project.tasks.register("myTask", MyCustomTask) {
group = "custom"
inputParameter = extension.inputParameter
}
}
}
在此示例中,MyExtension
类定义了一个 inputParameter
属性,可在构建脚本中设置。MyPlugin
类配置此扩展并使用其 inputParameter
值来配置 MyCustomTask
任务。然后,MyCustomTask
任务在其逻辑中使用此输入参数。
您可以在 延迟配置 中了解有关可在任务实现和扩展中使用的类型的更多信息。
使用约定添加默认配置
插件应在特定上下文中提供明智的默认值和标准,以减少用户需要做出的决策数量。使用 project
对象,您可以定义默认值。这些称为约定。
约定是使用默认值初始化的属性,用户可以在其构建脚本中覆盖这些属性。例如
interface GreetingPluginExtension {
val message: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Add the 'greeting' extension object
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
extension.message.convention("Hello from GreetingPlugin")
// Add a task that uses configuration from the extension object
project.task("hello") {
doLast {
println(extension.message.get())
}
}
}
}
apply<GreetingPlugin>()
interface GreetingPluginExtension {
Property<String> getMessage()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
// Add the 'greeting' extension object
def extension = project.extensions.create('greeting', GreetingPluginExtension)
extension.message.convention('Hello from GreetingPlugin')
// Add a task that uses configuration from the extension object
project.task('hello') {
doLast {
println extension.message.get()
}
}
}
}
apply plugin: GreetingPlugin
$ gradle -q hello Hello from GreetingPlugin
在此示例中,GreetingPluginExtension
是表示约定的类。message 属性是约定属性,其默认值为“Hello from GreetingPlugin”。
用户可以在其构建脚本中覆盖此值
GreetingPluginExtension {
message = "Custom message"
}
GreetingPluginExtension {
message = 'Custom message'
}
$ gradle -q hello
Custom message
将功能与约定分开
在插件中将功能与约定分开,使用户可以选择要应用的任务和约定。
例如,Java Base 插件提供无主见(即通用)功能,如 SourceSets
,而 Java 插件则添加了 Java 开发人员熟悉的任务和约定,如 classes
、jar
或 javadoc
。
在设计您自己的插件时,请考虑开发两个插件——一个用于功能,另一个用于约定——以向用户提供灵活性。
在下面的示例中,MyPlugin
包含约定,而 MyBasePlugin
定义功能。然后,MyPlugin
应用 MyBasePlugin
,这称为插件组合。要从另一个插件应用插件
import org.gradle.api.Plugin;
import org.gradle.api.Project;
public class MyBasePlugin implements Plugin<Project> {
public void apply(Project project) {
// define capabilities
}
}
import org.gradle.api.Plugin;
import org.gradle.api.Project;
public class MyPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getPlugins().apply(MyBasePlugin.class);
// define conventions
}
}
对插件做出反应
Gradle 插件实现中的常见模式是在构建中配置现有插件和任务的运行时行为。
例如,插件可以假设它应用于基于 Java 的项目,并自动重新配置标准源目录
public class InhouseStrongOpinionConventionJavaPlugin implements Plugin<Project> {
public void apply(Project project) {
// Careful! Eagerly appyling plugins has downsides, and is not always recommended.
project.getPlugins().apply(JavaPlugin.class);
SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
main.getJava().setSrcDirs(Arrays.asList("src"));
}
}
这种方法的缺点是它会自动强制项目应用 Java 插件,从而对其施加强烈的意见(即,降低灵活性和通用性)。实际上,应用插件的项目甚至可能不处理 Java 代码。
插件可以响应使用项目应用 Java 插件这一事实,而不是自动应用 Java 插件。只有在这种情况下,才会应用特定配置
public class InhouseConventionJavaPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getPlugins().withType(JavaPlugin.class, javaPlugin -> {
SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
main.getJava().setSrcDirs(Arrays.asList("src"));
});
}
}
如果没有任何充分理由假设使用项目具有预期设置,则响应插件比应用插件更可取。
同一概念适用于任务类型
public class InhouseConventionWarPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getTasks().withType(War.class).configureEach(war ->
war.setWebXml(project.file("src/someWeb.xml")));
}
}
响应构建功能
有两个主要用例
-
在报告或统计数据中使用构建功能的状态。
-
通过禁用不兼容的插件功能,逐步采用实验性 Gradle 功能。
下面是一个同时利用这两个用例的插件示例。
public abstract class MyPlugin implements Plugin<Project> {
@Inject
protected abstract BuildFeatures getBuildFeatures(); (1)
@Override
public void apply(Project p) {
BuildFeatures buildFeatures = getBuildFeatures();
Boolean configCacheRequested = buildFeatures.getConfigurationCache().getRequested() (2)
.getOrNull(); // could be null if user did not opt in nor opt out
String configCacheUsage = describeFeatureUsage(configCacheRequested);
MyReport myReport = new MyReport();
myReport.setConfigurationCacheUsage(configCacheUsage);
boolean isolatedProjectsActive = buildFeatures.getIsolatedProjects().getActive() (3)
.get(); // the active state is always defined
if (!isolatedProjectsActive) {
myOptionalPluginLogicIncompatibleWithIsolatedProjects();
}
}
private String describeFeatureUsage(Boolean requested) {
return requested == null ? "no preference" : requested ? "opt-in" : "opt-out";
}
private void myOptionalPluginLogicIncompatibleWithIsolatedProjects() {
}
}
1 | BuildFeatures 服务可以注入到插件、任务和其他受管类型中。 |
2 | 访问功能的requested 状态以进行报告。 |
3 | 使用功能的active 状态以禁用不兼容的功能。 |
构建功能属性
BuildFeature
状态属性用Provider<Boolean>
类型表示。
构建功能的BuildFeature.getRequested()
状态确定用户是否请求启用或禁用该功能。
当requested
提供程序值为
-
true
— 用户选择使用该功能 -
false
— 用户选择不使用该功能 -
undefined
— 用户既未选择使用该功能,也未选择不使用该功能
构建功能的BuildFeature.getActive()
状态始终是已定义的。它表示构建中该功能的有效状态。
当active
提供程序值为
-
true
— 该特性可能以特定于该特性的方式影响构建行为 -
false
— 该特性不会影响构建行为
请注意,active
状态不依赖于requested
状态。即使用户请求了某个特性,它也可能由于构建中使用了其他构建选项而不会处于活动状态。即使用户未指定首选项,Gradle 也可以默认激活某个特性。
提供默认依赖项
插件的实现有时需要使用外部依赖项。
您可能希望使用 Gradle 的依赖项管理机制自动下载工件,并稍后在插件中声明的任务类型的操作中使用它。理想情况下,插件实现不需要向用户询问该依赖项的坐标 - 它可以简单地预定义一个明智的默认版本。
我们来看一个下载包含用于进一步处理的数据的文件的插件示例。插件实现声明了一个自定义配置,允许使用依赖项坐标分配这些外部依赖项
public class DataProcessingPlugin implements Plugin<Project> {
public void apply(Project project) {
Configuration dataFiles = project.getConfigurations().create("dataFiles", c -> {
c.setVisible(false);
c.setCanBeConsumed(false);
c.setCanBeResolved(true);
c.setDescription("The data artifacts to be processed for this plugin.");
c.defaultDependencies(d -> d.add(project.getDependencies().create("org.myorg:data:1.4.6")));
});
project.getTasks().withType(DataProcessing.class).configureEach(
dataProcessing -> dataProcessing.getDataFiles().from(dataFiles));
}
}
abstract public class DataProcessing extends DefaultTask {
@InputFiles
abstract public ConfigurableFileCollection getDataFiles();
@TaskAction
public void process() {
System.out.println(getDataFiles().getFiles());
}
}
这种方法对最终用户很方便,因为无需主动声明依赖项。插件已经提供了有关此实现的所有详细信息。
但如果用户想要重新定义默认依赖项怎么办?
没问题。插件还公开了自定义配置,可用于分配不同的依赖项。实际上,默认依赖项被覆盖
plugins {
id("org.myorg.data-processing")
}
dependencies {
dataFiles("org.myorg:more-data:2.6")
}
plugins {
id 'org.myorg.data-processing'
}
dependencies {
dataFiles 'org.myorg:more-data:2.6'
}
您会发现,当在执行任务操作时任务需要外部依赖项时,此模式效果很好。您可以更进一步,通过公开扩展属性(例如JaCoCo 插件中的toolVersion
)来抽象要用于外部依赖项的版本。
最大程度减少外部库的使用
在 Gradle 项目中使用外部库可以带来极大的便利,但请注意,它们可能会引入复杂的依赖关系图。Gradle 的 buildEnvironment
任务可以帮助你将这些依赖关系可视化,包括插件的依赖关系。请记住,插件共享相同的类加载器,因此不同版本的同一库可能会出现冲突。
为了进行演示,我们假设以下构建脚本
plugins {
id("org.asciidoctor.jvm.convert") version "4.0.2"
}
plugins {
id 'org.asciidoctor.jvm.convert' version '4.0.2'
}
任务的输出清楚地指示了 classpath
配置的类路径
$ gradle buildEnvironment > Task :buildEnvironment ------------------------------------------------------------ Root project 'external-libraries' ------------------------------------------------------------ classpath \--- org.asciidoctor.jvm.convert:org.asciidoctor.jvm.convert.gradle.plugin:4.0.2 \--- org.asciidoctor:asciidoctor-gradle-jvm:4.0.2 +--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 | \--- org.tukaani:xz:1.6 +--- org.ysb33r.gradle:grolifant-herd:3.0.0 | +--- org.tukaani:xz:1.6 | +--- org.ysb33r.gradle:grolifant40:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.apache.commons:commons-collections4:4.4 | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 | | | +--- org.tukaani:xz:1.6 | | | +--- org.apache.commons:commons-collections4:4.4 | | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant50:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant40-legacy-api:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.apache.commons:commons-collections4:4.4 | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant60:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant70:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant60:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant80:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant60:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant70:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) +--- org.asciidoctor:asciidoctor-gradle-base:4.0.2 | \--- org.ysb33r.gradle:grolifant-herd:3.0.0 (*) \--- org.asciidoctor:asciidoctorj-api:2.5.7 (*) - Indicates repeated occurrences of a transitive dependency subtree. Gradle expands transitive dependency subtrees only once per project; repeat occurrences only display the root of the subtree, followed by this annotation. A web-based, searchable dependency report is available by adding the --scan option. BUILD SUCCESSFUL in 0s 1 actionable task: 1 executed
Gradle 插件不会在其自己的隔离类加载器中运行,因此你必须考虑是否真正需要一个库,或者一个更简单的解决方案就足够了。
对于作为任务执行的一部分执行的逻辑,请使用 Worker API,它允许你隔离库。
提供多种插件变体
配置其他插件变体的最便捷方法是使用 功能变体,这是所有应用 Java 插件之一的 Gradle 项目中可用的一个概念
dependencies {
implementation 'com.google.guava:guava:30.1-jre' // Regular dependency
featureVariant 'com.google.guava:guava-gwt:30.1-jre' // Feature variant dependency
}
在以下示例中,每个插件变体都独立开发。一个单独的源集被编译并打包到每个变体的单独 jar 中。
以下示例演示如何添加与 Gradle 7.0+ 兼容的变体,而“main”变体与较旧版本兼容
val gradle7 = sourceSets.create("gradle7")
java {
registerFeature(gradle7.name) {
usingSourceSet(gradle7)
capability(project.group.toString(), project.name, project.version.toString()) (1)
}
}
configurations.configureEach {
if (isCanBeConsumed && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
objects.named("7.0"))
}
}
}
tasks.named<Copy>(gradle7.processResourcesTaskName) { (3)
val copyPluginDescriptors = rootSpec.addChild()
copyPluginDescriptors.into("META-INF/gradle-plugins")
copyPluginDescriptors.from(tasks.pluginDescriptors)
}
dependencies {
"gradle7CompileOnly"(gradleApi()) (4)
}
def gradle7 = sourceSets.create('gradle7')
java {
registerFeature(gradle7.name) {
usingSourceSet(gradle7)
capability(project.group.toString(), project.name, project.version.toString()) (1)
}
}
configurations.configureEach {
if (canBeConsumed && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
objects.named(GradlePluginApiVersion, '7.0'))
}
}
}
tasks.named(gradle7.processResourcesTaskName) { (3)
def copyPluginDescriptors = rootSpec.addChild()
copyPluginDescriptors.into('META-INF/gradle-plugins')
copyPluginDescriptors.from(tasks.pluginDescriptors)
}
dependencies {
gradle7CompileOnly(gradleApi()) (4)
}
只有 Gradle 版本 7 或更高版本才能被变体明确地指定为目标,因为对它的支持只在 Gradle 7 中添加。 |
首先,我们为 Gradle7 插件变体声明一个单独的源集和一个功能变体。然后,我们进行一些特定的连接,将功能转换为一个适当的 Gradle 插件变体
1 | 将 隐式功能(对应于组件 GAV) 分配给变体。 |
2 | 将 Gradle API 版本属性 分配给 Gradle7 变体的所有 可消耗配置。Gradle 使用此信息来确定在插件解析期间选择哪个变体。 |
3 | 配置 processGradle7Resources 任务以确保插件描述符文件被添加到 Gradle7 变体 Jar 中。 |
4 | 为我们的新变体添加对 gradleApi() 的依赖,以便在编译时可以看到 API。 |
请注意,目前没有便捷的方法可以访问与你用于构建插件的 Gradle 版本不同的其他 Gradle 版本的 API。理想情况下,每个变体都应该能够声明对其支持的最小 Gradle 版本的 API 的依赖关系。这将在未来得到改进。
上述代码段假设你的插件的所有变体在相同的位置具有插件类。也就是说,如果你的插件类为 org.example.GreetingPlugin
,你需要在 src/gradle7/java/org/example
中创建该类的第二个变体。
使用多变体插件的特定版本变体
给定对多变体插件的依赖关系,Gradle 将在解析任何以下内容时自动选择与当前 Gradle 版本最匹配的变体
-
在
plugins {}
块 中指定的插件; -
buildscript
类路径依赖关系; -
出现在编译或运行时类路径上的 构建源 (
buildSrc
) 的根项目中的依赖关系; -
出现在编译或运行时类路径上,应用了 Java Gradle 插件开发插件 或 Kotlin DSL 插件 的项目中的依赖关系。
最匹配的变体是针对最高 Gradle API 版本且不超过当前构建的 Gradle 版本的变体。
在所有其他情况下,如果存在不指定受支持的 Gradle API 版本的插件变体,则首选该变体。
在使用插件作为依赖关系的项目中,可以请求支持不同 Gradle 版本的插件依赖关系的变体。这允许依赖于其他插件的多变体插件访问其 API,而这些 API 仅在其特定版本变体中提供。
此代码段使 上面定义的插件变体 gradle7
消耗其对其他多变体插件的依赖关系的匹配变体
configurations.configureEach {
if (isCanBeResolved && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
objects.named("7.0"))
}
}
}
configurations.configureEach {
if (canBeResolved && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
objects.named(GradlePluginApiVersion, '7.0'))
}
}
}
报告问题
插件可以通过 Gradle 的问题报告 API 报告问题。这些 API 报告有关构建期间发生的问题的丰富结构化信息。不同的用户界面(例如 Gradle 的控制台输出、构建扫描或 IDE)可以使用此信息以最合适的方式向用户传达问题。
以下示例显示了从插件报告的问题
public class ProblemReportingPlugin implements Plugin<Project> {
private final ProblemReporter problemReporter;
@Inject
public ProblemReportingPlugin(Problems problems) { (1)
this.problemReporter = problems.forNamespace("org.myorg"); (2)
}
public void apply(Project project) {
this.problemReporter.reporting(builder -> builder (3)
.label("Plugin 'x' is deprecated")
.details("The plugin 'x' is deprecated since version 2.5")
.solution("Please use plugin 'y'")
.severity(Severity.WARNING)
);
}
}
1 | Problem 服务被注入到插件中。 |
2 | 为插件创建问题报告器。虽然命名空间由插件作者决定,但建议使用插件 ID。 |
3 | 报告问题。此问题可恢复,以便继续构建。 |
有关完整示例,请参阅我们的端到端示例。
构建问题
报告问题时,可以提供各种信息。ProblemSpec 描述了可以提供的所有信息。
问题聚合
报告问题时,Gradle 会根据问题的类别标签通过 Tooling API 发送类似问题来聚合这些问题。
-
报告问题时,第一个出现的问题将作为ProblemDescriptor进行报告,其中包含有关该问题的完整信息。
-
相同问题的任何后续出现都将作为ProblemAggregationDescriptor进行报告。此描述符将出现在构建的末尾,并包含该问题的出现次数。
-
如果对于任何存储段(即类别和标签配对),收集到的出现次数大于 10.000,则它将立即发送,而不是在构建结束时发送。