IntelliJ Platform Plugin SDK Help

Plugins Targeting IntelliJ Platform-Based IDEs

Plugin projects can target any (custom) IDEs, as long as the products are based on the IntelliJ Platform. Such plugins are developed much like plugin projects that target IntelliJ IDEA.

Project configuration attributes common to projects targeting products other than IntelliJ IDEA are described on this page. Details particular to an IntelliJ Platform-based product are described on the individual product pages in Part VIII — Product Specific.

All the Gradle configuration attributes described here are discussed in-depth on the Configuring Gradle IntelliJ Plugin and the Gradle IntelliJ Plugin.

Getting Started

To create a new Gradle plugin project, follow the tutorial on the Creating a Plugin Gradle Project page. The tutorial produces a skeleton Gradle project suitable to use as a starting point.

Modifications are needed to the skeleton project's Gradle build script and plugin.xml files, as described below, and on the individual product pages in Part VIII — Product Specific. The Gradle build script is modified to specify the target product, determining the APIs available during development. The plugin.xml file is modified to declare the plugin's dependencies on modules or libraries.

Configuring Gradle Build Script to Target Products Other Than IntelliJ IDEA

The best practice is to use the intellij.type property to specify the target product. For example, PY for PyCharm Professional. Configuration using an intellij.type property is explained in the Configuring Plugin Projects Using a Product-Specific Attribute section below.

NOTE: Not all products have an intellij.type property defined by the Gradle IntelliJ Plugin, for example, Android Studio and PhpStorm. Please see their respective pages for configuration and Configuring Gradle Build Script Using the IntelliJ IDEA Product Attribute below.

Configuring Plugin Projects Using a Product-Specific Attribute

If the Gradle IntelliJ Plugin supports a target product directly, there will be an intellij.type property defined. Specifying the target as a product-specific intellij.type property has two advantages:

  • The APIs available to the plugin will be limited to only what is defined in the target product (unless additional plugin dependencies are specified).

  • The default IDE Development Instance for running the plugin will be the target product.

A Gradle build script snippet setting a plugin project to target PyCharm is shown below. The Gradle IntelliJ Plugin will fetch the matching build of PyCharm Professional to define the APIs available, and use that build of PyCharm (and associated JetBrains Runtime) as the Development Instance. No additional product-specific configuration needs to be set in the Gradle build script:

intellij { type.set("PY") version.set("2019.2.3") }
intellij { type = 'PY' version = '2019.2.3' }

Configuring Plugin Projects Using the IntelliJ IDEA Product Attribute

If the Gradle IntelliJ Plugin does not directly support an IntelliJ Platform-based product, the Gradle build script can still be configured to target the desired product. In this case, the build script is configured to use IntelliJ IDEA (Community or Ultimate Edition) as the basis for the available APIs. This does have the drawback that APIs not specific to the target product might accidentally be included in the plugin project. However, testing the plugin project in the target product itself helps to find such mistakes.

Additional configuration must be done to match the version of IntelliJ IDEA to the version of the target product. Understanding the relationship between build numbers is critical when using this approach to project configuration:

  • targetIDE is the (version-specific) IntelliJ Platform-based IDE in which the plugin is intended to run, such as Android Studio or PhpStorm.

  • baseIntelliJPlatformVersion is the (version-specific) IntelliJ Platform used in the build of the targetIDE. The IntelliJ Platform is defined by a specific build of the IntelliJ IDEA Community Edition. The Gradle plugin attribute intellij.version is set to be baseIntelliJPlatformVersion.

For API compatibility, the IntelliJ Platform version used in the targetIDE dictates the baseIntelliJPlatformVersion used for developing a plugin.

Matching Versions of the IntelliJ Platform with the Target IDE Version

The baseIntelliJPlatformVersion used in the targetIDE may not be readily apparent, depending on the product. See the individual product pages in Part VIII — Product Specific for exceptions.

To find the version of the IntelliJ Platform used to build the targetIDE, use the About dialog screen for the targetIDE. Next to Build # is the BRANCH.BUILD.FIX version of the targetIDE. In the example shown below, the BRANCH.BUILD.FIX version is 192.7142.41, and the product version is 2019.2.4. The version of the IntelliJ Platform used to build this product version is BRANCH.BUILD, or 192.7142

Example PhpStorm Splash Screen

If the product version isn't clear on the About screen, consult the individual product pages in Part VIII — Product Specific.

The Other IntelliJ IDEA Versions page is a way to find build numbers for every product version. Additional ways include hovering over the version number for a product in Toolbox App or examining the About screen for IntelliJ IDEA Community. In this example, IntelliJ IDEA Community Edition (which defines the IntelliJ Platform) for 2019.2.4 is build number 192.7142.36. Although the FIX versions are different, this is not uncommon between products, and the builds are still compatible. The BRANCH and BUILD numbers match, therefore in this PhpStorm example:

  • The targetIDE is PhpStorm, build 192.7142.41,

  • The baseIntelliJPlatformVersion (IntelliJ IDEA Community Edition) is build 192.7142.36

This information is used to configure the plugin project's Gradle build script and plugin.xml file.

Configuring Gradle Build Script Using the IntelliJ IDEA Product Attribute

Configuring a Gradle plugin project for using baseIntelliJPlatformVersion requires changing some default settings in the Gradle build script. Changes need to be made in two places: intellij extension and runIde task.

The Gradle plugin attributes describing the configuration of the IntelliJ Platform used to build the plugin project must be explicitly set in the intellij task. The intellij.type is IU because although the IntelliJ IDEA Community Edition defines the IntelliJ Platform, the PHP plugin is only compatible with IntelliJ IDEA Ultimate. The intellij.version is baseIntelliJPlatformVersion.

Any dependencies on targetIDE-specific plugins or modules must be declared in the intellij extension. Use the Gradle plugin attribute intellij.plugins to declare a dependency. See the specific product pages in Part VIII — Product Specific for the targetIDE plugin or module name.

The best practice is to modify the runIde task to use a local installation of targetIDE as the IDE Development Instance. Set the runIde.ideDir attribute to the (user-specific) absolute path of the targetIDE application. The exact path format varies by operating system.

This snippet is an example for configuring the Setup and Running DSLs in a Gradle build script specific to developing a plugin for targetIDE.

intellij { // Define IntelliJ Platform against which to build the plugin project. type.set("IU") // Use the IntelliJ Platform BRANCH.BUILD version matching // "targetIDE" (PhpStorm): version.set("192.7142.36") // baseIntelliJPlatformVersion // Require the targetIDE plugin or library. Use the stable version // compatible with intellij.version and intellij.type specified above: plugins.set(listOf("com.jetbrains.php:192.6603.42")) } runIde { // Absolute path to the installed targetIDE to use as IDE Development // Instance (the "Contents" directory is macOS specific): ideDir.set(file("/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/192.7142.41/PhpStorm.app/Contents")) }
intellij { // Define IntelliJ Platform against which to build the plugin project. type = 'IU' // Use the IntelliJ Platform BRANCH.BUILD version matching // "targetIDE" (PhpStorm): version = '192.7142.36' // baseIntelliJPlatformVersion // Require the targetIDE plugin or library. Use the stable version // compatible with intellij.version and intellij.type specified above: plugins = ['com.jetbrains.php:192.6603.42'] } runIde { // Absolute path to the installed targetIDE to use as IDE Development // Instance (the "Contents" directory is macOS specific): ideDir = file('/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/192.7142.41/PhpStorm.app/Contents') }

Configuring plugin.xml

As discussed on the Declaring Plugin Dependencies page of this guide, a plugin's dependency on Modules Specific to Functionality must be declared in plugin.xml. When using features (APIs) specific to the target product, a dependency on the target product module must be declared, as shown in the code snippet below. Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on com.intellij.modules.platform must be declared as discussed in Plugin Compatibility with IntelliJ Platform Products.

Continuing with the example of developing a plugin for PhpStorm:

<!-- Targeting PhpStorm, so is dependent on the PHP plugin --> <depends>com.jetbrains.php</depends> <depends>com.intellij.modules.platform</depends>
Last modified: 27 February 2024