IntelliJ Platform Plugin SDK Help

Gradle IntelliJ Plugin

The Gradle IntelliJ Plugin is a plugin for the Gradle build system to help configuring your environment for building, testing, verifying, and publishing plugins for IntelliJ-based IDEs.

This plugin allows you to build plugins for IntelliJ Platform using specified IntelliJ SDK and bundled or third-party plugins.

The plugin provides the functionalities like:

  • adding extra IntelliJ-specific dependencies

  • patching processResources tasks to fill some tags (name, version) in plugin.xml with appropriate values

  • patching compile tasks to instrument code with nullability assertions and form classes made with IntelliJ GUI Designer

  • additional build steps which might be helpful while developing plugins for IntelliJ platform

Usage

To enable this plugin in your Gradle-based project, register the plugin in the Gradle build script's plugins section:

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

When upgrading to 1.x version, please make sure to follow the migration guide to adjust your existing build script.

Snapshot Release

The Snapshot release is a pre-release version built nightly from the latest main branch – as it is built every day using the same version number, it's not recommended to use it for production builds.

For switching to the snapshot release, point Gradle to the dedicated snapshot repository by adding an entry to the Gradle settings file.

build.gradle.kts

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

settings.gradle.kts

pluginManagement { repositories { maven("https://oss.sonatype.org/content/repositories/snapshots/") gradlePluginPortal() } }

build.gradle

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

settings.gradle

pluginManagement { repositories { maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' } gradlePluginPortal() } }

Configuration

IntelliJ Extension

After the Gradle IntelliJ Plugin is applied, the intellij extension can be used to configure the plugin and common settings of the provided tasks.

It is mandatory to specify at least the intellij.version property.

Example:

intellij { version.set("2022.1.1") type.set("IU") plugins.set(listOf("com.jetbrains.php:221.5787.21")) }
intellij { version = "2022.1.1" type = "IU" plugins = ["com.jetbrains.php:221.5787.21"] }

version

All available JetBrains IDEs versions can be found at IntelliJ Artifacts page.

The version of the IntelliJ Platform IDE that will be used to build the plugin. Please see Plugin Compatibility with IntelliJ Platform Products for more details.

Required

true

Type

String

Acceptable values
  • version number: 2022.1.1 or IC-2022.1.1

  • build number: 221.5080.210 or IC-221.5080.210

  • snapshot: 221-EAP-SNAPSHOT or LATEST-EAP-SNAPSHOT

type

The type of the IntelliJ-based IDE distribution. The type may also be specified as a prefix of the value for the intellij.version property instead.

Type

String

Default value

IC

Acceptable values

To build against IDEs not supported directly by type, please see their corresponding page in Part VIII — Product Specific.

pluginName

The plugin name part used in the generated ZIP distribution: build/distributions/PluginName-1.0.0.zip and name of the plugin directory in the sandbox directory.

Type

String

Default value

${project.name}

localPath

The path to the locally installed IDE distribution that should be used to build the plugin. Using the intellij.localPath allows to build the plugin using an IDE that is not available in IntelliJ Platform Artifacts Repositories.

Type

String

Default value

null

Samples
  • Windows: C:\Users\user\AppData\Local\JetBrains\Toolbox\apps\IDEA-U\ch-0\211.7142.45

  • macOS: /Applications/Android Studio 4.2 Preview.app/Contents (note /Contents suffix)

  • Linux: /home/user/idea-IC-181.4445.78

localSourcesPath

The path to local archive with IDE sources. Used for resolving source files of the locally installed IDE distribution when intellij.localPath is specified.

Type

String

Default value

null

plugins

The list of bundled IDE plugins and plugins from JetBrains Marketplace or configured intellij.pluginsRepositories.

Please see Dependencies for more details.

Notes:

  • For plugins from JetBrains Marketplace, use format pluginId:version.

  • For bundled plugins, version must be omitted: e.g. org.intellij.groovy.

  • For subprojects, use project reference project(':subproject').

  • If you need to refer plugin's classes from your project, you also have to define a dependency in your plugin.xml file, see Dependencies.

Type

List<Any>

Default value

[]

Acceptable values
  • org.plugin.id:version[@channel] format, String type:

    • org.intellij.plugins.markdown:8.5.0

    • org.intellij.scala:2017.2.638@nightly

  • bundledPluginId format, String type:

    • org.intellij.groovy

  • project(...) format, Project type:

    • project(":projectName")

    • project(":plugin-subproject")

updateSinceUntilBuild

Enables patching plugin.xml with the values of patchPluginXml.sinceBuild and patchPluginXml.untilBuild properties.

Type

Boolean

Default value

true

sameSinceUntilBuild

Enables patching plugin.xml with the patchPluginXml.untilBuild using value of patchPluginXml.sinceBuild with * wildcard, like sinceBuild.*, e.g., 221.*.

Notes:

Type

Boolean

Default value

false

instrumentCode

Enables the instrumentation of Java classes with nullability assertions and compilation of forms created by IntelliJ GUI Designer.

Type

Boolean

Default value

true

sandboxDir

The path of sandbox directory that is used for running IDE with developed plugin.

Type

String

Default value

${project.buildDir}/idea-sandbox

intellijRepository

The IntelliJ-based IDE distributions repository URL.

Type

String

Default value

https://cache-redirector.jetbrains.com/www.jetbrains.com/intellij-repository

pluginsRepositories

Configures repositories for downloading plugin dependencies. See Maven Interface for details on Maven repository format.

Type

PluginsRepositoryConfiguration

Default value

pluginsRepositories { marketplace() }

Acceptable values
  • marketplace() - use Maven repository with plugins listed in JetBrains Marketplace

  • maven(repositoryUrl) - use custom Maven repository with plugins

  • maven { repositoryUrl } - use custom Maven repository with plugins where you can configure additional parameters (credentials, authentication, etc.)

  • custom(pluginsXmlUrl) - use Custom Plugin Repository

jreRepository

URL of repository for downloading JetBrains Runtime.

Type

String

Default value

null

ideaDependencyCachePath

Path to the directory where IDE dependency cache is stored. If not set, the dependency will be extracted next to the downloaded ZIP archive in Gradle cache directory.

Type

String

Default value

null

downloadSources

Enables downloading the IntelliJ Platform sources. It is enabled by default if the CI environment variable is not set – which is present on Continuous Integration environments, like GitHub Actions, TeamCity, and others.

Type

Boolean

Default value

!System.getenv().containsKey("CI")

configureDefaultDependencies

Enables configuration of the default IntelliJ Platform dependencies in the current project. Otherwise, the DependenciesUtils.intellij(), DependenciesUtils.intellijPlugin(), and DependenciesUtils.intellijPlugins() functions could be used for an explicit configuration.

Type

Boolean

Default value

true

extraDependencies

Configures extra dependency artifacts from the IntelliJ repository. The dependencies on them could be configured only explicitly using the DependenciesUtils.intellijExtra() function in the dependencies block.

Type

List<String>

Default value

[]

Tasks

buildPlugin

Assembles a plugin and prepares ZIP archive for deployment.

archiveBaseName

The base name of the ZIP archive.

This task is preconfigured automatically and takes the output artifacts of prepareSandbox and jarSearchableOptions tasks as an input.

Type

String

Default value

${prepareSandboxTask.pluginName}

buildSearchableOptions

Builds an index of UI components (searchable options) for the plugin. This task runs a headless IDE instance to collect all the available options provided by the plugin's Settings.

Note, that this is a runIde-based task with predefined arguments and all properties of the runIde task are also applied to buildSearchableOptions tasks.

outputDir

Type

File

Default value

build/searchableOptions

downloadRobotServerPlugin

Downloads robot-server plugin. The robot-server plugin is required for running the UI tests using the runIdeForUiTests task.

version

The version of the Robot Server Plugin to download.

Type

String

Default value

LATEST

pluginArchive

The Robot Server Plugin archive, downloaded by default to the Gradle cache.

Type

File

Default value

Gradle cache

outputDir

Location of the extracted archive.

Type

File

Default value

build/robotServerPlugin

instrumentCode

The following attributes help you to tune instrumenting behaviour in instrumentCode { ... } block.

compilerVersion

A version of instrumenting compiler. It's used in cases when targeting non-IntelliJ IDEA IDEs (e.g. CLion or Rider).

Type

String

Default value

Build number of the IDE dependency

jarSearchableOptions

Creates a JAR file with searchable options to be distributed with the plugin.

outputDir

The output directory where the JAR file will be created.

Type

String

Default value

build/searchableOptions

pluginName

The name of the plugin.

Type

String

Default value

intellij.pluginName

sandboxDir

The sandbox output directory.

Type

String

Default value

prepareSandbox.outputDir

listProductsReleases

List all available IntelliJ-based IDE releases with their updates. The result list is used for testing the plugin with Plugin Verifier using the runPluginVerifier task.

Plugin Verifier requires a list of the IDEs that will be used for verifying your plugin build against. The availability of the releases may change in time, i.e., due to security issues in one version – which will be later removed and replaced with an updated IDE release.

With the listProductsReleases task, it is possible to list the currently available IDEs matching given conditions, like platform types, since/until release versions. Such a list is fetched from the remote updates file: https://www.jetbrains.com/updates/updates.xml, parsed and filtered considering the specified listProductsReleases.types, listProductsReleases.sinceVersion, listProductsReleases.untilVersion (or listProductsReleases.sinceBuild, listProductsReleases.untilBuild) properties.

The result list is stored within the listProductsReleases.outputFile, which is used as a source for the Plugin Verifier if the runPluginVerifier task has no runPluginVerifier.ideVersions property specified, the output of the listProductsReleases task is used.

updatesFile

Path to the products releases update file.

Type

List<String>

Default value

Gradle cache

types

List of types of IDEs that will be listed in results.

Type

String

Default value

intellij.type

sinceVersion

Lower boundary of the listed results in product marketing version format, e.g., 2020.2.1. It takes precedence over listProductsReleases.sinceBuild property.

Type

String

Default value

intellij.version

untilVersion

Upper boundary of the listed results in product marketing version format, e.g., 2020.2.1. It takes precedence over listProductsReleases.untilBuild property.

Type

String

Default value

null

sinceBuild

Lower boundary of the listed results in build number format, like 192.

Type

String

Default value

intellij.version

untilBuild

Upper boundary of the listed results in build number format, like 192.

Type

String

Default value

null

releaseChannels

Release channels that product updates will be filtered with.

Type

Channel

Default value

EnumSet.allOf(ListProductsReleasesTask.Channel)

outputFile

Path to the file, where the output list will be stored.

Type

File

Default value

File("${project.buildDir}/listProductsReleases.txt")

androidStudioUpdatePath

For Android Studio releases, a separated storage for the updates is used.

Type

String

Default value

https://raw.githubusercontent.com/JetBrains/intellij-sdk-docs/main/topics/_generated/android_studio_releases.xml

patchPluginXml

Patches plugin.xml files with values provided to the task.

destinationDir

The directory where the patched plugin.xml will be written.

Type

String

Default value

${project.buildDir}/patchedPluginXmlFiles

pluginXmlFiles

The list of plugin.xml files to patch.

Type

List<File>

Default value

auto-discovered from the project

pluginDescription

The description of the plugin used in the <description> tag.

Type

String

Default value

null

sinceBuild

The lower bound of the version range to be patched used in the since-build attribute of the <idea-version> tag.

Type

String

Default value

intellij.version in Branch.Build.Fix format

untilBuild

The upper bound of the version range to be patched used in the until-build attribute of the <idea-version> tag.

Type

String

Default value

intellij.version in Branch.Build.* format

version

The version of the plugin used in the <version> tag.

Type

String

Default value

${project.version}

changeNotes

The change notes of the plugin used in the <change-notes> tag.

Type

String

Default value

null

pluginId

The ID of the plugin used in the <id> tag.

Type

String

Default value

null

prepareSandbox

Prepares sandbox directory with installed plugin and its dependencies.

pluginName

The name of the plugin.

Type

String

Default value

intellij.pluginName

configDir

The directory with the plugin configuration.

Type

String

Default value

${intellij.pluginName}/config

pluginJar

The input plugin JAR file used to prepare the sandbox.

Type

File

Default value

output of the jar task

librariesToIgnore

Libraries that will be ignored when preparing the sandbox. By default, excludes all libraries that are a part of the setupDependenciesTask.idea dependency.

Type

List<File>

Default value

org.jetbrains.intellij.tasks.SetupDependenciesTask.idea.get().jarFiles

pluginDependencies

List of dependencies of the current plugin.

Type

List<PluginDependency>

Default value

org.jetbrains.intellij.IntelliJPluginExtension.getPluginDependenciesList

prepareTestingSandbox

Prepares sandbox directory with installed plugin and its dependencies for testing purposes.

See prepareSandbox Task.

prepareUiTestingSandbox

Prepares sandbox directory with installed plugin and its dependencies for UI testing purposes.

See prepareSandbox Task.

publishPlugin

Publishes plugin to the remote JetBrains Marketplace repository.

The following attributes are a part of the Publishing DSL publishPlugin { ... } in which allows Gradle to upload plugin to JetBrains Marketplace. Note that you need to upload the plugin to the repository at least once manually (to specify options like the license, repository URL etc.) before uploads through Gradle can be used.

See the instruction on how to generate authentication token.

See Publishing Plugins with Gradle tutorial for step-by-step instructions.

token

Authentication token.

Required

Type

String

Default value

null

channels

List of channel names to upload plugin to.

Type

List<String>

Default value

["default"]

host

URL host of a plugin repository.

Type

String

Default value

JetBrains Marketplace

distributionFile

ZIP file of plugin to upload.

Type

File

Default value

output of the buildPlugin task

toolboxEnterprise

Specifies if the Toolbox Enterprise plugin repository service should be used. This feature is still in the incubating phase and is not yet available for public use.

Type

Boolean

Default value

false

runIde

Runs the IDE instance with the developed plugin installed.

runIde tasks extend the JavaExec Gradle task – all properties available in the JavaExec as well as the following ones can be used to configure the runIde task.

ideDir

The IDE dependency sources path. Configured automatically with the setupDependencies.idea dependency.

Type

File

Default value

setupDependencies.idea

jbrVersion

Custom JetBrains Runtime (JBR) version to use for running the IDE.

Type

String

Default value

null

Accepted values
  • 8u112b752.4

  • 8u202b1483.24

  • 11_0_2b159

jbrVariant

JetBrains Runtime (JBR) variant to use when running the IDE with the plugin.

Type

String

Default value

null

pluginsDir

Path to the plugins directory within the sandbox prepared with the prepareSandbox task. Provided to the idea.plugins.path system property.

Type

Directory

Default value

prepareSandbox.destinationDir

autoReloadPlugins

Enables auto-reload of dynamic plugins. Dynamic plugins will be reloaded automatically when their JARs are modified. This allows a much faster development cycle by avoiding a full restart of the development instance after code changes. Enabled by default in 2020.2 and higher.

See Enabling Auto-Reload for more details.

Type

Boolean

Default value

true

runIdeForUiTests

Runs the IDE instance with the developed plugin and robot-server installed and ready for UI testing.

See intellij-ui-test-robot project.

See runIde task for more details.

runIdePerformanceTest

Runs performance tests on the IDE with the developed plugin installed.

The runIdePerformanceTest task extends the RunIdeBase task, so all configuration attributes of JavaExec and runIde tasks can be used in the runIdePerformanceTest as well. See runIde task for more details.

Currently, the task is under adaptation; more documentation will be added in the future.

testDataDir

Path to directory with test projects and .ijperf files.

Type

String

Default value

null

artifactsDir

Path to directory where performance test artifacts (IDE logs, snapshots, screenshots, etc.) will be stored. If the directory doesn't exist, it will be created.

Type

String

Default value

null

profilerName

Name of the profiler which will be used during execution.

Type

ProfilerName

Default value

ProfilerName.ASYNC

Acceptable values
  • ProfilerName.ASYNC

  • ProfilerName.YOURKIT

runPluginVerifier

Runs the IntelliJ Plugin Verifier tool to check the binary compatibility with specified IDE builds (see also 验证插件兼容性).

Plugin Verifier DSL runPluginVerifier { ... } allows to define the list of IDEs used for the verification, as well as explicit tool version and any of the available options by proxifying them to the Verifier CLI.

ideVersions

IDEs to check, in intellij.version format, i.e.: ["IC-2019.3.5", "PS-2019.3.2"]. Check the available build versions on IntelliJ Platform Builds list.

Type

List<String>

Default value

output of the listProductsReleases task

verifierVersion

IntelliJ Plugin Verifier version. Do not change unless absolutely required.

Type

String

Default value

LATEST

verifierPath

Local path to the pre-downloaded IntelliJ Plugin Verifier JAR file. If set, runPluginVerifier.verifierVersion is ignored.

Type

String

Default value

path to the JAR file resolved using the runPluginVerifier.verifierVersion property

localPaths

A list of the paths to locally installed IDE distributions that should be used for verification in addition to those specified in runPluginVerifier.ideVersions.

Type

List<File>

Default value

[]

distributionFile

ZIP file of the plugin to verify. If empty, the task will be skipped.

Type

File

Default value

output of the buildPlugin task

failureLevel

Defines the verification level at which the task should fail if any reported issue matches. Can be set as FailureLevel enum or EnumSet<FailureLevel>.

Type

org.jetbrains.intellij.tasks.RunPluginVerifierTask.FailureLevel

Default value

FailureLevel.COMPATIBILITY_PROBLEMS

Accepted values
  • FailureLevel.COMPATIBILITY_WARNINGS - Compatibility warnings detected against the specified IDE version.

  • FailureLevel.COMPATIBILITY_PROBLEMS - Compatibility problems detected against the specified IDE version.

  • FailureLevel.DEPRECATED_API_USAGES - Plugin uses API marked as deprecated (@Deprecated).

  • FailureLevel.SCHEDULED_FOR_REMOVAL_API_USAGES - Plugin uses API marked as scheduled for removal (ApiStatus.@ScheduledForRemoval).

  • FailureLevel.EXPERIMENTAL_API_USAGES - Plugin uses API marked as experimental (ApiStatus.@Experimental).

  • FailureLevel.INTERNAL_API_USAGES - Plugin uses API marked as internal (ApiStatus.@Internal).

  • FailureLevel.OVERRIDE_ONLY_API_USAGES - Override-only API is used incorrectly (ApiStatus.@OverrideOnly).

  • FailureLevel.NON_EXTENDABLE_API_USAGES - Non-extendable API is used incorrectly (ApiStatus.@NonExtendable).

  • FailureLevel.PLUGIN_STRUCTURE_WARNINGS - The structure of the plugin is not valid.

  • FailureLevel.MISSING_DEPENDENCIES - Plugin has some dependencies missing.

  • FailureLevel.INVALID_PLUGIN - "Provided plugin artifact is not valid."

  • FailureLevel.NOT_DYNAMIC - "Plugin cannot be loaded/unloaded without IDE restart."

  • FailureLevel.ALL - All of the above

  • FailureLevel.NONE - None of above

verificationReportsDir

The path to directory where verification reports will be saved.

Type

String

Default value

${project.buildDir}/reports/pluginVerifier

downloadDir

The path to directory where IDEs used for the verification will be downloaded.

Type

String

Default value

System.getProperty("plugin.verifier.home.dir")/ides or System.getProperty("user.home")/.pluginVerifier/ides or system temporary directory.

jbrVersion

Custom JetBrains Runtime (JBR) version to use for running the verification.

Type

String

Default value

null

Acceptable values
  • 8u112b752.4

  • 8u202b1483.24

  • 11_0_2b159

jbrVariant

JetBrains Runtime (JBR) variant to use when running the verification.

Type

String

Default value

null

runtimeDir

The path to directory containing JVM runtime, overrides runPluginVerifier.jbrVersion.

Type

String

Default value

null

externalPrefixes

The list of classes prefixes from the external libraries. The Plugin Verifier will not report No such class for classes of these packages.

Type

List<String>

Default value

[]

teamCityOutputFormat

A flag that controls the output format - if set to true, the TeamCity Tests Format – the TeamCity compatible output will be returned to stdout.

Type

Boolean

Default value

false

subsystemsToCheck

Specifies which subsystems of IDE should be checked.

Type

String

Default value

all

Acceptable values
  • all

  • android-only

  • without-android

setupDependencies

Setups required dependencies for building and running project. This task is automatically added to the "After Sync" Gradle trigger to make the IntelliJ SDK dependency available for IntelliJ IDEA right after the Gradle synchronization.

idea

This task exposes the setupDependencies.idea property which contains a reference to the resolved IDE dependency used for building the plugin.

This property can be referred in Gradle configuration to access IDE dependency classpath.

signPlugin

Signs the ZIP archive with the provided key using marketplace-zip-signer library.

To sign the plugin before publishing to JetBrains Marketplace with the signPlugin task, it is required to provide a certificate chain and a private key with its password using signPlugin { ... } Plugin Signing DSL.

As soon as signPlugin.privateKey (or signPlugin.privateKeyFile) and signPlugin.certificateChain (or signPlugin.certificateChainFile) properties are specified, the task will be executed automatically right before the publishPlugin task.

For more details, see Plugin Signing article.

certificateChain

A string containing X509 certificates. The first certificate from the chain will be used as a certificate authority (CA). Refers to cert CLI option.

Type

String

Default value

null

certificateChainFile

A file containing X509 certificates. The first certificate from the chain will be used as a certificate authority (CA). Refers to cert-file CLI option.

Type

File

Default value

null

privateKey

Encoded private key in PEM format. Refers to key CLI option.

Type

String

Default value

null

privateKeyFile

A file with encoded private key in PEM format. Refers to key-file CLI option.

Type

File

Default value

null

password

Password required to decrypt the private key. Refers to key-pass CLI option.

Type

String

Default value

null

cliVersion

Returns the version of JetBrains Marketplace ZIP Signer CLI that will be used.

Type

String

Default value

LATEST

cliPath

Path to JetBrains Marketplace ZIP Signer CLI file. Takes precedence over signPlugin.cliVersion.

Type

String

Default value

null

keyStore

KeyStore file path. Refers to ks CLI option.

Type

String

Default value

null

keyStorePassword

KeyStore password.

Type

String

Default value

null

keyStoreKeyAlias

KeyStore key alias. Refers to ks-key-alias CLI option.

Type

String

Default value

null

keyStoreType

KeyStore type.

Type

String

Default value

null

keyStoreProviderName

JCA KeyStore Provider name. Refers to ks-provider-name CLI option.

Type

String

Default value

null

inputArchiveFile

Input, unsigned ZIP archive file. Refers to in CLI option.

Provided by the buildPlugin task.

outputArchiveFile

Output, signed ZIP archive file. Refers to out CLI option.

Predefined with the name of the ZIP archive file with -signed name suffix attached.

Type

File

verifyPlugin

Validates completeness and contents of plugin.xml descriptors as well as plugin archive structure.

ignoreFailures

Specifies whether the build should fail when the verifications performed by this task fail.

Type

Boolean

Default value

false

ignoreWarnings

Specifies whether the build should fail when the verifications performed by this task emit warnings.

Type

Boolean

Default value

true

ignoreUnacceptableWarnings

Specifies whether the build should fail when the verifications performed by this task emit unacceptable warnings.

Type

Boolean

Default value

false

pluginDir

The location of the built plugin file which will be used for verification.

Type

File

Default value

${prepareSandboxTask.destinationDir}/${prepareSandboxTask.pluginName}

verifyPluginConfiguration

Validates the plugin project configuration:

  • The patchPluginXml.sinceBuild property can't be lower than the major version of the currently used IntelliJ SDK set with the intellij.version.

  • The sourceCompatibility property of the Java configuration can't be lower than the Java version used for assembling the IntelliJ SDK specified by the intellij.version.

  • The targetCompatibility property of the Java configuration can't be higher than the Java version required for running IDE in the version specified by the intellij.version or patchPluginXml.sinceBuild properties.

  • The jvmTarget property of the Kotlin configuration (if used) can't be higher than the Java version required for running IDE in the version specified by the intellij.version or patchPluginXml.sinceBuild properties.

  • The languageVersion property of the Kotlin configuration (if used) can't be lower than the Kotlin bundled with IDE in the version specified by the intellij.version or patchPluginXml.sinceBuild properties.

  • The apiVersion property of the Kotlin configuration (if used) can't be higher than the Kotlin bundled with IDE in the version specified by the intellij.version or patchPluginXml.sinceBuild properties.

  • The dependency on the Kotlin Standard Library (stdlib) is automatically added when using the Gradle Kotlin plugin and may conflict with the version provided with the IntelliJ Platform.

Last modified: 29 九月 2022