Configuring Gradle Projects

Configuring the Gradle IntelliJ Plugin for Building IntelliJ Platform Plugin Projects

By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.

If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type. IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.

Configuring the Gradle Plugin for Running IntelliJ Platform Plugin Projects

By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin. Using the corresponding JetBrains Runtime is also the default, so for this use-case no further configuration is required.

Managing Directories Used by the Gradle Plugin

There are several attributes to control where the Gradle plugin places directories for downloads and use by the IDE Development Instance.

The location of the sandbox home directory and its subdirectories can be controlled with Gradle plugin attributes. The intellij.sandboxDirectory attribute is used to set the path for the sandbox directory to be used while running the plugin in an IDE Development Instance. Locations of the sandbox subdirectories can be controlled using the runIde.configDirectory, runIde.pluginsDirectory, and runIde.systemDirectory attributes. If the intellij.sandboxDirectory path is explicitly set, the subdirectory attributes default to the new sandbox directory.

The storage location of downloaded IDE versions and components defaults to the Gradle cache directory. However, it can be controlled by setting the intellij.ideaDependencyCachePath attribute.

Controlling Downloads by the Gradle Plugin

As mentioned in the section about configuring the IntelliJ Platform used for building plugin projects, the Gradle plugin will fetch the version of the IntelliJ Platform specified by the default or by the intellij attributes. Standardizing the versions of the Gradle plugin and Gradle system across projects will minimize the time spent downloading versions.

There are controls for managing the Gradle IntelliJ Plugin version, and the version of Gradle itself. The plugin version is defined in the plugins {...} section of a project's Gradle build script. The version of Gradle is defined in $PROJECT_ROOT$/gradle/wrapper/gradle-wrapper.properties.

Patching the Plugin Configuration File

A plugin project's plugin.xml file has element values that are "patched" at build time from the attributes of the patchPluginXml task. As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's plugin.xml file:

• If a patchPluginXml attribute default value is defined, the attribute value will be patched in plugin.xml regardless of whether the patchPluginXml task appears in the Gradle build script.

  • For example, the default values for the attributes patchPluginXml.sinceBuild and patchPluginXml.untilBuild are defined based on the declared (or default) value of intellij.version. So by default patchPluginXml.sinceBuild and patchPluginXml.untilBuild are substituted into the <idea-version> element's since-build and until-build attributes in the plugin.xml file.

• If a patchPluginXml attribute value is explicitly defined, the attribute value will be substituted in plugin.xml.

  • If both patchPluginXml.sinceBuild and patchPluginXml.untilBuild attributes are explicitly set, both are substituted in plugin.xml.

  • If one attribute is explicitly set (e.g. patchPluginXml.sinceBuild) and one is not (e.g. patchPluginXml.untilBuild has a default value,) both attributes are patched at their respective (explicit and default) values.

• For no substitution of the <idea-version> element's since-build and until-build attributes, one of the following must appear in the Gradle build script:

  • Either set intellij.updateSinceUntilBuild to false, which will disable substituting both since-build and until-build attributes,

The best practice to avoid confusion is to replace the elements in plugin.xml that will be patched by the Gradle plugin with a comment. That way, the values for these parameters do not appear in two places in the source code. The Gradle plugin will add the necessary elements as part of the patching process. For those patchPluginXml attributes that contain descriptions such as patchPluginXml.changeNotes and patchPluginXml.pluginDescription, a CDATA block is not necessary when using HTML elements.

As discussed in Components of a Wizard-Generated Gradle IntelliJ Platform Plugin, the Gradle properties project.version, project.group, and rootProject.name are all generated based on the input to the Wizard. However, the Gradle IntelliJ Plugin does not combine and substitute those Gradle properties for the default <id> and <name> elements in the plugin.xml file.

The best practice is to keep project.version current. By default, if you modify project.version in Gradle build script, the Gradle plugin will automatically update the <version> value in the plugin.xml file. This practice keeps all version declarations synchronized.

Verifying Plugin

The Gradle plugin provides two tasks that allow for running integrity and compatibility tests:

• verifyPlugin task - validates completeness and contents of plugin.xml descriptors as well as plugin's archive structure,

• runPluginVerifier task - runs the IntelliJ Plugin Verifier tool to check the binary compatibility with specified IntelliJ IDE builds.

Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against. See Plugin Verifier for more information.

Publishing with the Gradle Plugin

Please review the Publishing Plugins with Gradle page before using the publishPlugin task. That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials.

Plugins Targeting IntelliJ IDEA

IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward Gradle plugin configuration.

• Determine the version of IntelliJ IDEA to use for building the plugin project; this is the desired version of the IntelliJ Platform. This can be EAP (default) or determined from the build number ranges.

  • If a production version of IntelliJ IDEA is the desired target, set the intellij.version property accordingly.

  • Set the necessary plugin dependencies, if any.

• If the plugin project should be run or debugged in an IDE Development Instance based on the same IntelliJ IDEA version, no further attributes need to be set for the IDE Development Instance. This is the default behavior and is the most common use case.

  • If the plugin project should be run or debugged in an IDE Development Instance based on an alternate version of the IntelliJ Platform, set the Running DSL attribute accordingly.

  • If the plugin project should be run using a JetBrains Runtime other than the default for the IDE Development Instance, specify the JetBrains Runtime version.

• Set the appropriate attributes for patching the plugin.xml file.

Plugins Targeting Alternate IntelliJ Platform-Based IDEs

Gradle also supports developing plugins to run in IDEs that are based on the IntelliJ Platform. For more information, see the Developing for Multiple Products page of this guide.