使用Gradle开发插件_gradle com.intellij:openapi

该系列翻译托管在 IntelliJ-Platform-SDK-DevGuide，如有任何指点请提Issue。

使用Gradle开发插件

将Gradle构建支持功能添加到IntelliJ平台需要使用到最近发布的Gradle构建系统和IntelliJ IDEA(Community或者Ultimate版)。

1.0 下载安装IntelliJ IDEA

下载并安装IntelliJ IDEA Ultimate版或者IntelliJ IDEA Community Edition版。

1.1 确保启用“Gradle”插件和“Plugin DevKit”插件

您可以点击 Settings | Plugins 来验证插件是否启用。

1.2 创建插件项目

IntelliJ IDEA支持使用Gradle自动创建新的插件项目，并自动执行build.gradle中所有必要的设置。这也可以用于将现有插件转换为Gradle，如果Gradle在本例中无法转换现有项目，您需要将源码复制到新项目中。

要做到这一点，需要在IntelliJ IDEA中创建一个新项目，打开 File | New… | Project, 并在弹出的对话框中选择Gradle。并在“Additional Libraries and Frameworks”一栏中，勾选 “IntelliJ Platform Plugin”。

项目创建向导现在将指导您一步步完成项目创建的过程。您需要指定组ID、伪ID和版本：

建议选择Use default gradle wrapper选项，这样IntelliJ IDEA将自动安装运行Gradle任务所需的一切东西。

最后，还需要指定一个将要使用的JVM Gradle，它可以是Project JDK。当项目创建后您还可以通过点击 Settings | Build, Execution, Deployment | Build Tools | Gradle 来配置该路径。

1.3 配置Gradle插件项目

IntelliJ平台提供了对基于Gradle插件项目的支持gradle-intellij-plugin。有关更多信息，请参考Gradle plugin README。例如，要配置 Sandbox Home 目录的位置，在项目的 build.gradle文件中包含以下内容：

intellij {
  sandboxDirectory = "$project.buildDir/myCustom-sandbox"
}
1
2
3

有关Sandbox Home默认主目录位置和内容的详细信息，请参阅IDE开发实例。

1.4 在现有插件中添加Gradle支持

要将Gradle支持添加到现有的插件项目中，请在根目录下创建 build.gradle文件，其中至少包含以下内容：

buildscript {
    repositories {
        mavenCentral()
    }
}

plugins {
    id "org.jetbrains.intellij" version "0.3.0"
}

apply plugin: 'idea'
apply plugin: 'org.jetbrains.intellij'
apply plugin: 'java'

intellij {
    version 'IC-2016.3' //IntelliJ IDEA 2016.3 dependency; for a full list of IntelliJ IDEA releases please see https://www.jetbrains.com/intellij-repository/releases
    plugins 'coverage' //Bundled plugin dependencies
    pluginName 'plugin_name_goes_here'
}

group 'org.jetbrains'
version '1.2' // Plugin version
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

然后，使用系统路径上配置的Gradle可执行文件，在命令行窗口执行以下命令：

gradle cleanIdea idea
1

这将清理任何现有的IntelliJ IDEA配置文件，并生成一个由IntelliJ IDEA识别的新的Gradle构建配置文件。刷新您的项目，然后点击 View | Tool Windows | Gradle 查看到Gradle工具窗口。可以看到IntelliJ IDEA已经识别到了Gradle。

1.5 运行一个简单的插件

现在将一个新的 HelloAction类添加到Java文件夹中，并在 META-INF文件夹中添加 plugin.xml和 pluginIcon.svg文件。有关 pluginIcon.svg文件的更多信息，请参见Plugin Icon页面。

import com.intellij.openapi.actionSystem.*;
import com.intellij.openapi.project.Project;
import com.intellij.openapi.ui.Messages;

public class HelloAction extends AnAction {
  public HelloAction() {
    super("Hello");
  }

  public void actionPerformed(AnActionEvent event) {
    Project project = event.getProject();
    Messages.showMessageDialog(project, "Hello world!", "Greeting", Messages.getInformationIcon());
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

<idea-plugin>
  <id>org.jetbrains</id>
  <name>Hello Action Project</name>
  <version>0.0.1</version>
  <vendor email="dummy" url="dummy">dummy</vendor>

  <depends>com.intellij.modules.lang</depends>

  <extensions defaultExtensionNs="com.intellij">
  </extensions>

  <actions>
    <group id="MyPlugin.SampleMenu" text="Greeting" description="Greeting menu">
      <add-to-group group-id="MainMenu" anchor="last"/>
      <action id="Myplugin.Textboxes" class="HelloAction" text="Hello" description="Says hello"/>
    </group>
  </actions>

</idea-plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

打开Gradle工具窗口并搜索 runIde任务。如果列表中没有该选项，请点击顶部的刷新按钮，双击来运行它。

或者添加一个新的Gradle运行配置，配置如下：

启动新的Gradle运行配置。在运行窗口中，可以看到类似下面的输出信息。

最后，当IDE启动时，帮助菜单的右边应该有一个新的菜单。您的插件现在已经通过Gradle配置好了。

使用Gradle发布插件

只要配置了Gradle支持，您就可以自动构建插件并将其部署到JetBrains Plugin Repository。要做到这一点，需要您先将插件发布到插件仓库。有关详细信息，请参阅publishing a plugin。

2.0添加您的账户凭证

为了将插件提交到插件仓库，首先需要您提供JetBrains帐户凭证。这些凭证信息通常存储在Gradle properties。所以千万不要将这些凭证添加到源代码提交信息中。

将以下信息放在项目根目录下名为 gradle.properties的文件中，或者放在 GRADLE_HOME/gradle.properties中。

intellijPublishUsername="YOUR_USERNAME_HERE"
intellijPublishPassword="YOUR_PASSWORD_HERE"
1
2

然后在 build.gradle文件中的 publishPlugin任务中引用这些值：

publishPlugin {
  username intellijPublishUsername
  password intellijPublishPassword
}
1
2
3
4

如果将 gradle.properties文件放置在项目的根目录中，请确保版本控制工具忽略此文件。例如在Git中，可以将以下行添加到 .gitignore文件中：

gradle.properties
1

或者，您可以创建一个默认的 gradle.properties模板，并默认 git忽略将来对该文件的任何更改。为此，请检查默认模板并执行以下命令：

git update-index --assume-unchanged gradle.properties
1

如果您的项目已经有一个 gradle.properties文件，您可以创建一个自定义 *.properties文件，并手动加载它。例如：

apply from: "/path/to/custom.properties"
1

2.1配置插件

Gradle-IntelliJ-plugin为如何使用Gradle构建您的插件提供了许多[configuration options](configuration options)(配置选项)。其中一个最重要的是 version（版本）。 默认情况下，如果在构建脚本中修改 version，Gradle插件将自动更新 plugin.xml文件中的 <version>。

Gradle插件还将更新 plugin.xml文件中的 <idea-version since-build=.../>，以与 intellij.version匹配，直到当前主版本中的最后一个版本为止。当然，您也可以通过将 intellij.updateSinceUntilBuild选项设置为 false来禁用此功能。

apply plugin: 'org.jetbrains.intellij'

intellij {
    version '15.0.1'
    pluginName 'idear'
    intellij.updateSinceUntilBuild false //Disables updating since-build attribute in plugin.xml
}

group 'com.jetbrains'
version '1.2' // Update me!
1
2
3
4
5
6
7
8
9
10

当您使用包含上述代码段的构建脚本运行 Gradle runIdea时，Gradle将从Snapshot(基于时间的)或Release(基于版本)的仓库下载IntelliJ IDEA的适当版本，配置插件沙箱，安装插件，并启动新的IDE。这个任务可以直接从命令行运行，而不需要任何其他工具帮助。

为了获得最稳定的效果，插件开发人员应该使用固定的版本，而不是 LATEST-TRUNK-SNAPSHOT（最新版本）。有关IntelliJ平台的可用版本信息，您可以参考以下URL获取最新的更新：

• Releases: https://www.jetbrains.com/intellij-repository/releases
• Snapshots: https://www.jetbrains.com/intellij-repository/snapshots

2.3部署您的插件

部署插件的第一步是确认插件能否正常工作。您可以通过在新的IntelliJ IDEA Community Edition版本上选择 installing your plugin from disk（从磁盘上安装插件）来验证这一点。一旦您确信插件可以按照预期正常运行，发布前请确保插件版本已更新，因为JetBrains插件仓库不会接受具有相同版本的多个文件。要将插件的新版本部署到JetBrains插件仓库，请执行以下Gradle命令：

gradle publishPlugin
1

现在查看插件的最新版本是否出现在 Plugin Repository中。如果插件部署成功，在符合条件的IntelliJ平台上安装您的插件的任何用户都将在启动IDE时收到可用更新的通知。

您还可以通过配置 intellij.publish.channel属性将插件部署到您选择要发布的渠道。当该属性为空时，将使用默认的插件仓库，并且所有JetBrains plugin repository用户都可以访问到。当然，您也可以发布到任意命名的渠道。但是不管怎样这些非默认的发布渠道都将被视为单独的仓库。当使用非默认发布渠道时，用户需要添加一个新的custom plugin repository（自定义插件库）来安装插件。例如，如果指定 intellij.publish.channel 'canary'，则用户将需要添加 https://plugins.jetbrains.com/plugins/canary/list仓库来安装插件并接收更新。流行的渠道名称包括：

• alpha: https://plugins.jetbrains.com/plugins/alpha/list
• beta: https://plugins.jetbrains.com/plugins/beta/list
• eap: https://plugins.jetbrains.com/plugins/eap/list