Getting Started with Gradle

Gradle is the preferred solution for creating IntelliJ Platform plugins. The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based development. These IntelliJ IDEA plugins are Gradle and Plugin DevKit, which are enabled by default. To verify these plugins are installed and enabled, see the help section about Managing Plugins.

Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard

Creating new Gradle-based IntelliJ Platform plugin projects is performed using the dedicated generator available in the New Project Wizard. The generator creates all the necessary project files based on a few template inputs.

Create IDE Plugin

Launch the New Project wizard via the action and provide the following information:

Select the IDE Plugin generator type from the list on the left.
Specify the project Name and Location.
Choose the Plugin option in the project Type.
Choose the Language the plugin will use for implementation. For this example select the Java option. See Kotlin for Plugin Developers for more information.
Provide the Group which is typically an inverted company domain (e.g. com.example.mycompany). It is used for the Gradle property project.group value in the project's Gradle build script.
Provide the Artifact which is the default name of the build project artifact (without a version). It is also used for the Gradle property rootProject.name value in the project's settings.gradle.kts file. For this example, enter my_plugin.
Select JDK 11. This JDK will be the default JRE used to run Gradle, and the JDK version used to compile the plugin Java sources.

After providing all the information, click the Create button to generate the project.

Components of a Wizard-Generated Gradle IntelliJ Platform Plugin

For the example my_plugin, the IDE Plugin generator creates the following directory content:

my_plugin
├── .run
│   └── Run IDE with Plugin.run.xml
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src
│   ├── main
│   │   ├── java
│   │   └── resources
│   │       └── META-INF
│   │           └── plugin.xml
│   └── test
│       ├── java
│       └── resources
├── .gitignore
├── build.gradle.kts
├── gradlew
├── gradlew.bat
└── settings.gradle.kts

The default IntelliJ Platform build.gradle.kts file (see next paragraph).
The settings.gradle.kts file, containing a definition of the rootProject.name.
The Gradle Wrapper files, and in particular the gradle-wrapper.properties file, which specifies the version of Gradle to be used to build the plugin. If needed, the IntelliJ IDEA Gradle plugin downloads the version of Gradle specified in this file.
The META-INF directory under the default main source set contains the plugin configuration file.
The Run Plugin run configuration.

The generated my_plugin project build.gradle.kts file:

plugins {
  id("java")
  id("org.jetbrains.intellij") version "1.7.0"
}

group = "com.example"
version = "1.0-SNAPSHOT"

repositories {
  mavenCentral()
}

// Configure Gradle IntelliJ Plugin
// Read more: https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html
intellij {
  version.set("2021.3")
  type.set("IC") // Target IDE Platform

  plugins.set(listOf(/* Plugin Dependencies */))
}

tasks {
  // Set the JVM compatibility versions
  withType<JavaCompile> {
    sourceCompatibility = "11"
    targetCompatibility = "11"
  }

  patchPluginXml {
    sinceBuild.set("213")
    untilBuild.set("223.*")
  }

  signPlugin {
    certificateChain.set(System.getenv("CERTIFICATE_CHAIN"))
    privateKey.set(System.getenv("PRIVATE_KEY"))
    password.set(System.getenv("PRIVATE_KEY_PASSWORD"))
  }

  publishPlugin {
    token.set(System.getenv("PUBLISH_TOKEN"))
  }
}

Two Gradle plugins are explicitly declared:
- The Gradle Java plugin.
- The Gradle IntelliJ Plugin.
The Group from the New Project wizard is the project.group value.
The sourceCompatibility line is injected to enforce using Java 11 JDK to compile Java sources.
The values of the intellij.version and intellij.type properties specify the version and type of the IntelliJ Platform to be used to build the plugin.
The empty placeholder list for plugin dependencies.
The values of the patchPluginXml.sinceBuild and patchPluginXml.untilBuild properties specifying the minimum and maximum versions of the IDE build the plugin is compatible with.
The initial signPlugin and publishPlugin tasks configuration. See the Publishing Plugins with Gradle section for more information.

Plugin Gradle Properties and Plugin Configuration File Elements

The Gradle properties rootProject.name and project.group will not, in general, match the respective plugin configuration file plugin.xml elements <name> and <id>. There is no IntelliJ Platform-related reason they should as they serve different functions.

The <name> element (used as the plugin's display name) is often the same as rootProject.name, but it can be more explanatory.

The <id> value must be a unique identifier over all plugins, typically a concatenation of the specified Group and Artifact. Please note that it is impossible to change the <id> of a published plugin without losing automatic updates for existing installations.

Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin

Converting a DevKit-based plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project:

Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
Delete all the artifacts of the DevKit-based project:
- .idea directory
- [modulename].iml file
- out directory
Arrange the existing source files within the project directory in the Gradle source set format.
Use the New Project Wizard as though creating a new Gradle project from scratch.
On the New Project choose the IDE Plugin generator and set the values of:
- Group to the existing package in the initial source set.
- Artifact to the name of the existing plugin.
- Name to the name of the directory where the existing plugin is located, e.g. if the plugin project base directory is /Users/john/Projects/old_plugin, it should be the old_plugin.
- Location to the name of the plugin's parent directory, e.g. if the plugin project base directory is /Users/john/Projects/old_plugin, it should be the /Users/john/Projects.
Click Finish to create the new Gradle-based plugin.
Add more modules using Gradle source sets as needed.

Running a Simple Gradle-Based IntelliJ Platform Plugin

Gradle projects are run from the IDE's Gradle Tool window.

Adding Code to the Project

Before running my_plugin, some code can be added to provide simple functionality. See the Creating Actions tutorial for step-by-step instructions for adding a menu action.

Executing the Plugin

The IDE Plugin generator automatically creates the Run Plugin run configuration that can be executed via the action or can be found in the Gradle tool window under the Run Configurations node.

To execute the Gradle runIde task directly, open the Gradle tool window and search for the runIde task under the Tasks node. If it's not on the list, hit the re-import button in the toolbar at the top of the Gradle tool window. When the runIde task is visible, double-click it to execute.

To debug your plugin in a standalone IDE instance, please see How to Debug Your Own IntelliJ IDEA Instance blog post.

Last modified: 29 九月 2022