使用Gradle開發插件

該系列翻譯託管在 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"
}

有關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

然後，使用系統路徑上配置的Gradle可執行文件，在命令行窗口執行以下命令：

gradle cleanIdea idea

這將清理任何現有的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());
  }
}

<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>

打開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"

然後在 build.gradle文件中的 publishPlugin任務中引用這些值：

publishPlugin {
  username intellijPublishUsername
  password intellijPublishPassword
}

如果將 gradle.properties文件放置在項目的根目錄中，請確保版本控制工具忽略此文件。例如在Git中，可以將以下行添加到 .gitignore文件中：

gradle.properties

或者，您可以創建一個默認的 gradle.properties模板，並默認 git忽略將來對該文件的任何更改。爲此，請檢查默認模板並執行以下命令：

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

如果您的項目已經有一個 gradle.properties文件，您可以創建一個自定義 *.properties文件，並手動加載它。例如：

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

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!

當您使用包含上述代碼段的構建腳本運行 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

現在查看插件的最新版本是否出現在 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