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 valuespatching 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:
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
settings.gradle.kts
build.gradle
settings.gradle
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:
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
orIC-2022.1.1
build number:
221.5080.210
orIC-221.5080.210
snapshot:
221-EAP-SNAPSHOT
orLATEST-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
CL
- CLionPS
- PhpStormRD
- RiderGO
- GoLandAI
- Android StudioJPS
- JPS-onlyGW
- Gateway
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:
Useful for building plugins against EAP builds.
If
patchPluginXml.untilBuild
has a value set, thenintellij.sameSinceUntilBuild
is ignored.
- 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 Marketplacemaven(repositoryUrl)
- use custom Maven repository with pluginsmaven { 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
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
sandboxDir
The sandbox output directory.
- Type
String
- Default value
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
types
List of types of IDEs that will be listed in results.
- Type
String
- Default value
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
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
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
inBranch.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
inBranch.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
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
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
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
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 aboveFailureLevel.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
orSystem.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 theintellij.version
.The
sourceCompatibility
property of the Java configuration can't be lower than the Java version used for assembling the IntelliJ SDK specified by theintellij.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 theintellij.version
orpatchPluginXml.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 theintellij.version
orpatchPluginXml.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 theintellij.version
orpatchPluginXml.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 theintellij.version
orpatchPluginXml.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.