Cake.IntelliJ.Recipe 0.3.0

Cake.IntelliJ.Recipe

基于约定的 Cake 脚本，用于构建 IntelliJ 插件。

目录

• Cake.IntelliJ.Recipe
  • 目录
  • 安装
  • 使用
  • 讨论
  • 设置
    • 分析
    • 频道
    • Grade-Verbosity
    • Marketplace-ID
    • PluginVerifier
    • 发布
  • 模板更改
    • 读我
    • 变更日志
    • 发布和预发布
  • CI 系统
    • GitHub Actions
      • 操作系统
      • java 版本
      • gradle
    • AppVeyor
      • 操作系统
      • java 版本
      • gradle
  • 维护者
  • 贡献
    • 贡献者
  • 许可证

安装

#load nuget:?package=Cake.IntelliJ.Recipe

使用

#load nuget:?package=Cake.IntelliJ.Recipe

Environment.SetVariableNames();

IntelliJBuildParameters.SetParameters(
  context: Context,
  buildSystem: BuildSystem,
  sourceDirectoryPath: "./src",
  title: "Best-Plugin-Ever",
  repositoryOwner: "nils-a");

IntelliJBuildParameters.PrintParameters(Context);

ToolSettings.SetToolSettings(context: Context);

IntelliJBuild.Run();

请注意，Cake.IntelliJ.Recipe 包裹了一个 gradle 构建，并使用了 org.jetbrains.intellij gradle 插件的任务。建议从 https://github.com/JetBrains/intellij-platform-plugin-template 创建插件。

讨论

如果您有问题，请搜索现有的问题或在 Cake GitHub 仓库中创建新的讨论，使用 extension-q-a 类别。

设置

分析

Cake 目标 IntelliJAnalyze 在每次构建时运行，并用于运行代码分析。

在此目标中的默认操作是运行以下 gradle 任务： detekt、ktlintCheck 和 verifyPlugin。

如果出于某种原因需要更改此操作（例如，对于不使用 detekt 和 ktlint 而依赖其他内容的插件），可以使用 intelliJAnalyzerTasks 设置来配置要调用的任务。

IntelliJBuildParameters.SetParameters(
  // ... all other parameters ...
  intelliJAnalyzerTasks: new[]{ "check", "verifyPlugin" }
);

频道

有关发布频道的设置有：

• pluginReleaseChannel 默认为 "Stable"
• pluginPreReleaseChannel 默认为 "Beta"
• pluginCiBuildChannel 默认为 "Alpha"
• shouldPublishPluginCiBuilds 默认为 false
• pluginChannelGradleProperty 默认为 "marketplaceChannel"

请参阅 发布和预发布 了解它们的含义。

Grade-Verbosity

运行 gradle 的冗长性具有自己的设置：gradleVerbosity。（默认设置为 GradleLogLevel.Default）

请注意，当将 Cake 的冗长性设置为 diagnostic 时，机密信息仍然保密。然而，将 gradle 的冗长性设置为 GradleLogLevel.Debug 将会在日志中打印出所有机密信息。

Marketplace-ID

当发布是自动化的，可以创建 Twitter 和 Gitter 消息。为了让他们链接到市场中的插件页面，需要一个 marketplaceId 设置。可以从市场中的 URL 获取 marketplaceId，例如对于 https://plugins.jetbrains.com/plugin/15698-test-rider，marketplaceId 是 15698-test-rider。

Twitter、Gitter 等其他所有设置都遵循 Cake.Recipe。

PluginVerifier

gradle 任务 runPluginVerifier 运行 JetBrains 插件验证器。此任务被映射到 Cake 目标 Run-Plugin-Verifier，在 CI 构建上运行。如果出于任何原因不希望在 CI 构建上运行，可以使用 shouldRunPluginVerifier 设置来禁用运行。

例如：如果构建在 Linux 上（例如，GitHub 动作 Linux 运行器没有足够的空闲空间用于插件验证器），则不运行插件验证器。

IntelliJBuildParameters.SetParameters(
  // ... all other parameters ...
  shouldRunPluginVerifier: !IsRunningOnLinux()
);

发布

要将插件发布到 JetBrains 市场的地方，需要一个 令牌。令牌必须以环境变量的形式提供，然后在 gradle 构建中检索。从 https://github.com/JetBrains/intellij-platform-plugin-template 创建的插件默认使用 PUBLISH_TOKEN 变量名。

此外，与“正常”的基于 gradle 的发布一样，插件的第一次发布必须手动进行。

模板更改

当为新创建自 https://github.com/JetBrains/intellij-platform-plugin-template 的插件创建新的配方时，必须做出以下更改

读我

标准模板利用 org.jetbrains.intellij gradle-plugin 自动从 Readme.md 的内容更新 plugin.xml 的 <description>，这是完全可以接受的。

如果 Readme.md 被移动（比如上移一个文件夹以适应配方结构），则需要修复。

build.gradle.kts 中的默认代码是

// Extract the  section from README.md and provide for the plugin's manifest
pluginDescription(
    closure {
        File("./README.md").readText().lines().run {
            val start = ""
            val end = ""

            if (!containsAll(listOf(start, end))) {
                throw GradleException("Plugin description section not found in README.md:\n$start ... $end")
            }
            subList(indexOf(start) + 1, indexOf(end))
        }.joinToString("\n").run { markdownToHTML(this) }
    }
)

这应该指向 Readme.md 的新位置，例如

// ...
  File("../README.md").readText().lines().run {
// ...

或者，可以从 build.gradle.kts 中删除整个代码块，并手动将 <description> 添加到 plugin.xml 中。请注意，描述是 html 格式，所有的实体都已编码。（例如 <description>&lt;h3&gt;这是插件！&lt;/h3&gt;</description>）。

变更日志

标准模板利用 org.jetbrains.changelog gradle-plugin 来保持 Changelog.md 与当前版本号的更新，并在构建时将最新的更改复制到 plugin.xml 的 <change-notes> 部分。

目前 Cake.IntellJ.Recipe 不会将 GitHub 发布中的版本说明（由 Cake.Recipe 自动创建并首选）与插件中显示的最新更改之间的差距。

建议将指向 GitHub 发布页面的链接放置在 plugin.xml 的 change-notes 中。

为此，这里有两个应在 build.gradle.kts 中删除的部分

在 patchPluginXml 中

// Get the latest available change notes from the changelog file
changeNotes(
    closure {
        changelog.getLatest().toHTML()
    }
)

以及在 publishPlugin 中

dependsOn("patchChangelog")

并且需要在 plugin.xml 中的 change-notes 手动添加。像下面这样

<change-notes>
  &lt;a href="https://github.com/nils-a/test-rider/releases"&gt;&lt;h3&gt;See GitHub Releases&lt;/h3&gt;&lt;/a&gt;
</change-notes>

是建议的。

发布和预发布

原始的 Cake.Recipe 知道三种类型的发布

• 发布（通过向主分支添加标签创建）会将发布包发布到发布包源（通常是 NuGet）。
• 标记了预发布版（通过在另一个（即不是主分支）的分支上添加标签创建）会将预发布包发布到发布包源（通常是 NuGet）。
• 由 CI 构建 生成的预发布版会将预发布包发布到其他包源（例如 MyGet、Azure、GPR）。

JetBrains 市场本身没有预发布版的概念。此外，除了创建一个自定义插件仓库（参见 自定义插件仓库）之外，在 JetBrains 市场上没有其他替代方案。

然而，市场确实有 "频道" 的概念。频道在所有方面都被视为独立的仓库，并且只有默认频道（命名为 Stable）可浏览和搜索。

Cake.IntelliJ.Recipe 为上述提到的发布类型准备了以下设置

• pluginReleaseChannel （默认："Stable"）作为发布发布的频道名称。
• pluginPreReleaseChannel （默认 "Beta"）作为发布标记预发布版的频道名称。
• pluginCiBuildChannel （默认 "Alpha"）作为发布 CI 构建的频道名称。

注意，发布到 JetBrains 市场的内容需要经过审核，因此它们不会被公众立即访问。同样，出于同样的原因，默认情况下禁止发布 CI 构建。使用 shouldPublishPluginCiBuilds （默认 false）以启用它。

为了使这起作用，Cake.IntelliJ.Recipe 将通过项目属性将选定的频道传递给 gradle。该属性的名称设置为 pluginChannelGradleProperty （默认："marketplaceChannel"），并且必须在 build.gradle.kts 中的 publishPlugin 任务中获取。

代码

publishPlugin {
    token(System.getenv("PUBLISH_TOKEN"))
    // pluginVersion is based on the SemVer (https://semver.org) and supports pre-release labels, like 2.1.7-alpha.3
    // Specify pre-release label to publish the plugin in a custom Release Channel automatically. Read more:
    // https://jetbrains.org/intellij/sdk/docs/tutorials/build_system/deployment.html#specifying-a-release-channel
    channels(pluginVersion.split('-').getOrElse(1) { "default" }.split('.').first())
}

应该替换为

publishPlugin {
    token(System.getenv("PUBLISH_TOKEN"))
    channels(marketplaceChannel)
}

另外需要在靠近以下文本行的位置添加一行：

val marketplaceChannel: String by project

// 从 gradle.properties 文件中导入变量

此外，在 gradle.properties 中还必须提供一个默认值

marketplaceChannel = development

CI 系统

总的来说，从 Cake.Recipe 应用的内容也适用于此处。需要对 gradle 和/或 java 做一些修改才能正确运行。具体来说

• 确保有一个指向构建插件的 JAVA_HOME 环境变量，它指向所需的 java 版本
• 缓存 ~/.gradle/caches 和 ~/.gradle/wrapper

GitHub Actions

操作系统

待办事项：检查为什么在第一次测试中在 windows 上构建的速度如此慢。

java 版本

要设置正确的 java 版本，使用以下命令

# Setup Java 1.8 environment which is needed to build
- name: Setup Java
  uses: actions/setup-java@v1
  with:
    java-version: 1.8

（备注：只有当版本 1.8 是构建您的插件所需的版本时，才选择 java 版本 1.8。）

gradle

建议额外的 gradle 缓存。同时，仅在 GitHub Actions 上，建议使用 Gradle Wrapper Validation Action 以确保只检查签入的官方版本的 gradlew。

# Validates the gradle wrappers and saves us from getting malicious PRs
- name: Gradle Wrapper Validation
  uses: gradle/wrapper-validation-action@v1

# Cache Gradle dependencies
- name: Setup Gradle Dependencies Cache
  uses: actions/cache@v2
  with:
    path: ~/.gradle/caches
    key: ${{ runner.os }}-gradle-caches-${{ hashFiles('**/*.gradle', '**/*.gradle.kts', 'gradle.properties') }}

# Cache Gradle Wrapper
- name: Setup Gradle Wrapper Cache
  uses: actions/cache@v2
  with:
    path: ~/.gradle/wrapper
    key: ${{ runner.os }}-gradle-wrapper-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}

AppVeyor

操作系统

由于 https://github.com/cake-contrib/Cake.IntelliJ.Recipe/issues/15，当前的 AppVeyor build 在 Linux 上失败

java 版本

AppVeyor 预装了多个 java 版本（所有都是基于 openJDK 的）。

要在 Linux 上选择版本，可以使用 stack 定义

stack: jdk 8

要选择Windows上的版本，需要手动正确设置JAVA_HOME。路径有文档说明 （请参阅文档）

environment:
  JAVA_HOME="C:\Program Files\Java\jdk1.8.0"

（备注：如果构建插件需要版本1.8（或8），请选择java版本1.8。）

gradle

建议对gradle进行额外的缓存。请记住，gradle缓存可能会相当大，和使用时可能存在限制

cache:
  - '%USERPROFILE%\.gradle\caches -> **\*.gradle, **\*.gradle.kts, gradle.properties'
  - '%USERPROFILE%\.gradle\wrapper -> **\gradle\wrapper\gradle-wrapper.properties'

维护者

Nils Andresen @nils-a

贡献

Cake.IntelliJ.Recipe遵循贡献者协定行为准则。

我们接受拉取请求。请参阅贡献文件了解如何为Cake.IntelliJ.Recipe做出贡献。

小提醒：如果编辑Readme文件，请遵守standard-readme规范。

本项目遵循all-contributors规范。欢迎一切类型的贡献！

贡献者

感谢以下这些出色的人员（《emoji key》）

<table> <tr> <td align="center"><a href="https://github.com/nils-a"><img src="https://avatars3.githubusercontent.com/u/349188?v=4?s=100" width="100px;" alt=""/><br />_{<b>Nils Andresen</b>}</a><br /><a href="https://github.com/cake-contrib/Cake.IntelliJ.Recipe/commits?author=nils-a" title="Code">💻</a></td> </tr> </table>

许可证

MIT许可© Nils Andresen