发布插件是使其可供他人使用的主要方式。虽然你可以发布到私有仓库以限制访问,但发布到 Gradle 插件门户 将使你的插件可供全世界任何人使用。

plugin portal page

本指南将向你展示如何使用 com.gradle.plugin-publish 插件,通过便捷的 DSL 将插件发布到 Gradle 插件门户。这种方法简化了配置步骤,并提供了验证检查,以确保你的插件符合 Gradle 插件门户的标准。

前提条件

本教程需要一个现有的 Gradle 插件项目。如果你没有,请使用Greeting 插件示例

尝试发布此插件将安全地因权限错误而失败,因此不必担心用一个简单的示例插件弄乱 Gradle 插件门户。

账户设置

在发布插件之前,你必须在 Gradle 插件门户上创建一个账户。按照注册页面上的说明创建账户,并从你的个人资料页面的“API Keys”选项卡获取 API 密钥。

plugin portal registration page

将你的 API 密钥存储在 Gradle 配置中 (gradle.publish.key 和 gradle.publish.secret),或者使用像 Seauc Credentials plugin 或 Gradle Credentials plugin 这样的插件进行安全管理。

plugin portal api keys

通常的做法是将文本复制并粘贴到你的 $HOME/.gradle/gradle.properties 文件中,但你也可以将其放置在任何其他有效位置。插件所需的只是在执行相应的插件门户任务时,gradle.publish.keygradle.publish.secret 可作为项目属性使用。

如果你担心将凭据放在 gradle.properties 中,可以查看 Seauc Credentials pluginGradle Credentials plugin

或者,你可以通过 GRADLE_PUBLISH_KEYGRADLE_PUBLISH_SECRET 环境变量提供 API 密钥。这种方法可能适用于 CI/CD 流水线。

添加插件发布插件

要发布你的插件,请将 com.gradle.plugin-publish 插件添加到你项目的 build.gradlebuild.gradle.kts 文件中

build.gradle.kts
plugins {
    id("com.gradle.plugin-publish") version "1.2.1"
}
build.gradle
plugins {
    id 'com.gradle.plugin-publish' version '1.2.1'
}

可以在 Gradle 插件门户 上找到 Plugin Publishing Plugin 的最新版本。

从 1.0.0 版本开始,Plugin Publish Plugin 会自动应用 Java Gradle 插件开发插件(协助开发 Gradle 插件)和 Maven 发布插件(生成插件发布元数据)。如果使用旧版本的 Plugin Publish Plugin,则必须显式应用这些辅助插件。

配置插件发布插件

在你的 build.gradlebuild.gradle.kts 文件中配置 com.gradle.plugin-publish 插件。

build.gradle.kts
group = "io.github.johndoe" (1)
version = "1.0" (2)

gradlePlugin { (3)
    website = "<substitute your project website>" (4)
    vcsUrl = "<uri to project source repository>" (5)

    // ... (6)
}
build.gradle
group = 'io.github.johndoe' (1)
version = '1.0'     (2)

gradlePlugin { (3)
    website = '<substitute your project website>' (4)
    vcsUrl = '<uri to project source repository>' (5)

    // ... (6)
}
1 确保你的项目设置了 group,它用于在 Gradle 插件门户的仓库中标识你为插件发布的 artifacts(jar 和元数据),并且应描述插件作者或插件所属的组织。
2 设置你的项目版本,它也将用作你的插件版本。
3 使用 Java Gradle 插件开发插件 提供的 gradlePlugin 块来配置插件发布的更多选项。
4 设置你的插件项目的网站。
5 提供源代码仓库 URI,以便其他人想要贡献时可以找到它。
6 为你想要发布的每个插件设置特定属性;参见下一节。

使用 gradlePlugin{} 块为所有插件定义通用属性,例如 group、version、website 和 source repository

build.gradle.kts
gradlePlugin { (1)
    // ... (2)

    plugins { (3)
        create("greetingsPlugin") { (4)
            id = "<your plugin identifier>" (5)
            displayName = "<short displayable name for plugin>" (6)
            description = "<human-readable description of what your plugin is about>" (7)
            tags = listOf("tags", "for", "your", "plugins") (8)
            implementationClass = "<your plugin class>"
        }
    }
}
build.gradle
gradlePlugin { (1)
    // ... (2)

    plugins { (3)
        greetingsPlugin { (4)
            id = '<your plugin identifier>' (5)
            displayName = '<short displayable name for plugin>' (6)
            description = '<human-readable description of what your plugin is about>' (7)
            tags.set(['tags', 'for', 'your', 'plugins']) (8)
            implementationClass = '<your plugin class>'
        }
    }
}
1 插件特定配置也放在 gradlePlugin 块中。
2 这是我们之前添加全局属性的地方。
3 你发布的每个插件在 plugins 中都有自己的块。
4 你发布的每个插件的插件块名称必须是唯一的;这是你的构建仅在本地使用的属性,不会作为发布的一部分。
5 设置插件的唯一 id,它将在发布中被标识。
6 设置插件的可读名称。
7 设置将在门户上显示的描述。它为想要使用你的插件的人提供有用信息。
8 指定你的插件所属的类别。这使得需要该功能的人更容易发现你的插件。

例如,考虑已经发布到 Gradle 插件门户的 GradleTest 插件 的配置。

build.gradle.kts
gradlePlugin {
    website = "https://github.com/ysb33r/gradleTest"
    vcsUrl = "https://github.com/ysb33r/gradleTest.git"
    plugins {
        create("gradletestPlugin") {
            id = "org.ysb33r.gradletest"
            displayName = "Plugin for compatibility testing of Gradle plugins"
            description = "A plugin that helps you test your plugin against a variety of Gradle versions"
            tags = listOf("testing", "integrationTesting", "compatibility")
            implementationClass = "org.ysb33r.gradle.gradletest.GradleTestPlugin"
        }
    }
}
build.gradle
gradlePlugin {
    website = 'https://github.com/ysb33r/gradleTest'
    vcsUrl = 'https://github.com/ysb33r/gradleTest.git'
    plugins {
        gradletestPlugin {
            id = 'org.ysb33r.gradletest'
            displayName = 'Plugin for compatibility testing of Gradle plugins'
            description = 'A plugin that helps you test your plugin against a variety of Gradle versions'
            tags.addAll('testing', 'integrationTesting', 'compatibility')
            implementationClass = 'org.ysb33r.gradle.gradletest.GradleTestPlugin'
        }
    }
}

如果你浏览 Gradle 插件门户上与 GradleTest 插件 相关的页面,你将看到指定的元数据显示方式。

plugin portal plugin page

源码和 Javadoc

Plugin Publish Plugin 会自动为你的插件发布生成并发布 Javadoc 和 sources JAR

对 Artifact 进行签名

从 Plugin Publish Plugin 1.0.0 版本开始,已发布的插件 artifact 签名已自动化。要启用它,只需要在你的构建中应用 signing 插件即可。

Shadow 依赖项

从 Plugin Publish Plugin 1.0.0 版本开始,shadowing 你的插件依赖项(即,将其发布为 fat jar)已自动化。要启用它,只需要在你的构建中应用 com.gradleup.shadow 插件即可。

发布插件

如果你将插件内部发布供组织内部使用,可以像发布任何其他代码 artifact 一样发布它。请参阅关于发布 artifact 的 IvyMaven 章。

如果你有兴趣发布你的插件以供更广泛的 Gradle 社区使用,你可以将其发布到 Gradle 插件门户。该网站提供搜索和收集 Gradle 社区贡献的插件信息的功能。请参阅关于如何在该网站上发布插件的相应章节

本地发布

要检查你发布的插件 artifact 的外观或仅在本地或公司内部使用它,你可以将其发布到任何 Maven 仓库,包括本地文件夹。你只需配置用于发布的仓库。然后,你可以运行 publish 任务将你的插件发布到你定义的所有仓库(但不包括 Gradle 插件门户)。

build.gradle.kts
publishing {
    repositories {
        maven {
            name = "localPluginRepository"
            url = uri("../local-plugin-repository")
        }
    }
}
build.gradle
publishing {
    repositories {
        maven {
            name = 'localPluginRepository'
            url = file('../local-plugin-repository')
        }
    }
}

要在另一个构建中使用该仓库,请将其添加到你的 settings.gradle(.kts) 文件中的 pluginManagement {} 块的仓库 中。

发布到插件门户

使用 publishPlugin 任务发布插件

$ ./gradlew publishPlugins

在发布之前,你可以使用 --validate-only 标志验证你的插件

$ ./gradlew publishPlugins --validate-only

如果你尚未为 Gradle 插件门户配置 gradle.properties,可以在命令行上指定它们

$ ./gradlew publishPlugins -Pgradle.publish.key=<key> -Pgradle.publish.secret=<secret>
如果你尝试使用本节中使用的 ID 发布示例 Greeting 插件,你将遇到权限失败。这是预期的,并确保门户不会被多个实验性和重复的问候类型插件淹没。

批准后,你的插件将在 Gradle 插件门户上可用,供其他人发现和使用。

使用已发布的插件

成功发布插件后,它不会立即出现在门户上。它还需要通过审批流程,这个过程对于你的插件的初始版本来说是手动且相对较慢的,但对于后续版本则是完全自动的。更多详情,请参阅此处

你的插件获批后,可以在格式为 https://plugins.gradle.org/plugin/<your-plugin-id> 的 URL 上找到使用说明。例如,Greeting 插件示例已在门户上,地址为 https://plugins.gradle.org/plugin/org.example.greeting

未通过 Gradle 插件门户发布的插件

如果你的插件未使用 Java Gradle 插件开发插件 发布,则发布将缺少 插件标记 Artifact,它是 plugins DSL 用于定位插件所需的。在这种情况下,在另一个项目中解析插件的推荐方法是将 resolutionStrategy 部分添加到项目的 settings 文件中的 pluginManagement {} 块,如下所示。

settings.gradle.kts
resolutionStrategy {
    eachPlugin {
        if (requested.id.namespace == "org.example") {
            useModule("org.example:custom-plugin:${requested.version}")
        }
    }
}
settings.gradle
resolutionStrategy {
    eachPlugin {
        if (requested.id.namespace == 'org.example') {
            useModule("org.example:custom-plugin:${requested.version}")
        }
    }
}