IntelliJ Platform Gradle Plugin (2.x)

The IntelliJ Platform Gradle Plugin 2.x is a plugin for the Gradle build system to help configure environments for building, testing, verifying, and publishing plugins for IntelliJ-based IDEs. It is a successor of Gradle IntelliJ Plugin (1.x).

Requirements

IntelliJ Platform Gradle Plugin 2.x requires the following minimal versions:

IntelliJ Platform: 2022.3
Gradle: 8.2
See the Gradle Installation guide on how to upgrade.
Java Runtime: 17
See Gradle JVM in Settings | Build, Execution, Deployment | Build Tools | Gradle.

Usage

To apply the IntelliJ Platform Gradle Plugin to a project, add the following entry to the plugins block in the build.gradle.kts file:

plugins {
  id("org.jetbrains.intellij.platform") version "2.0.0-rc2"
}

If migrating from the Gradle IntelliJ Plugin 1.x, replace the old org.jetbrains.intellij identifier to org.jetbrains.intellij.platform and apply its latest 2.0.0-rc2 version.

Snapshot Release

To use the latest snapshot versions, add the following to the settings.gradle.kts file:

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

Plugins

The IntelliJ Platform Gradle Plugin consists of plugins which can be applied depending on the purpose. By default, the Platform plugin (org.jetbrains.intellij.platform) should be applied to the main plugin project module.

When working with the Multi-Module Project Structure it is required to use Module plugin (org.jetbrains.intellij.platform.module) instead to creating tasks and configurations specific to the main module only.

The Settings plugin (org.jetbrains.intellij.platform.settings) allows for adding plugin development related repositories right in the settings.gradle.kts file if project configuration involves Dependency Resolution Management.

Attaching Sources

To attach IntelliJ Platform sources in the IDE, the Download sources setting has to be enabled in IDE versions 2023.2 and later. This option respects the downloadSources property, which is enabled by default.

In Settings | Advanced Settings enable option Download sources in section Build Tools. Gradle. Then invoke Reload All Gradle Projects action from the Gradle tool window.

In Settings | Build, Execution, Deployment | Build Tools | Gradle enable Download sources for dependencies. Then invoke the Reload All Gradle Projects action from the Gradle tool window.

No additional IDE settings are required.

The attaching sources is handed by the Plugin DevKit plugin thus it's recommended to use always the latest available IDE release.

If the opened compiled class has no sources available locally, the Plugin DevKit plugin will detect the relevant source coordinates and provide an action to Download IntelliJ Platform sources or Attach $API_NAME$ sources.

Configuration

Setting Up Repositories

All IntelliJ Platform SDK artifacts are available via IntelliJ Maven repositories (see IntelliJ Platform Artifacts Repositories), which exist in three variants:

releases
snapshots
nightly (only selected artifacts)

Example:

Setup Maven Central and defaultRepositories() repositories:

repositories {
  mavenCentral()

  intellijPlatform {
    defaultRepositories()
  }
}

Example #2:

Build a plugin against a release version of the IntelliJ Platform with dependency on a plugin from the JetBrains Marketplace:

repositories {
  mavenCentral()

  intellijPlatform {
    releases()
    marketplace()
  }
}

See Repositories Extension on how to configure additional repositories.

Dependency Resolution Management

To access the IntelliJ Platform Gradle Plugin within the settings.gradle.kts to use with dependencyResolutionManagement, add:

import org.jetbrains.intellij.platform.gradle.extensions.intellijPlatform

plugins {
  id("org.jetbrains.intellij.platform.settings") version "2.0.0-rc2"
}

dependencyResolutionManagement {
  repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS

  repositories {
    mavenCentral()

    intellijPlatform {
      defaultRepositories()
    }
  }
}

Cache Redirector

Some repositories, by default, point to JetBrains Cache Redirector to provide better resource resolution. However, it is possible to use the direct repository URL, if available.

To switch off the default usage of JetBrains Cache Redirector, see the useCacheRedirector Gradle property.

Setting Up IntelliJ Platform

Dependencies and repositories are handled using explicit entries within dependencies {} and repositories {} blocks in build.gradle.kts file.

A minimum configuration for targeting IntelliJ IDEA Community 2023.3:

repositories {
  mavenCentral()

  intellijPlatform {
    defaultRepositories()
  }
}

dependencies {
  intellijPlatform {
    intellijIdeaCommunity("2023.3")
  }
}

The intellijIdeaCommunity in the previous sample is one of the extension functions available for adding IntelliJ Platform dependencies to the project. See Dependencies Extension on how to target other IDEs.

Parametrize IntelliJ Platform Dependency

As a fallback, intellijPlatform extension can be used to allow dynamic configuration of the target platform, for example, via gradle.properties:

platformType = IC
platformVersion = 2023.3

The above Gradle properties can be referenced in the build.gradle.kts file with:

dependencies {
  intellijPlatform {
    val type = providers.gradleProperty("platformType")
    val version = providers.gradleProperty("platformVersion")

    create(type, version)
  }
}

The intellijPlatform helper accepts also the IntelliJPlatformType type:

import org.jetbrains.intellij.platform.gradle.IntelliJPlatformType

dependencies {
  intellijPlatform {
    val version = providers.gradleProperty("platformVersion")

    create(IntelliJPlatformType.IntellijIdeaUltimate, version)
  }
}

Local IntelliJ Platform IDE Instance

It is possible to refer to the locally available IntelliJ-based IDE using the local helper function:

repositories {
  intellijPlatform {
    defaultRepositories()
  }
}

dependencies {
  intellijPlatform {
    local("/Users/user/Applications/IntelliJ IDEA Ultimate.app")
  }
}

Setting Up Plugin Dependencies

To specify a dependency on a plugin, it is important to distinguish bundled plugins from plugins available in JetBrains Marketplace.

The Dependencies Extension provides a set of helpers to manage plugin dependencies:

repositories {
  intellijPlatform {
    defaultRepositories()
  }
}

dependencies {
  intellijPlatform {
    intellijIdeaCommunity("2024.1.4")
    instrumentationTools()

    bundledPlugin("com.intellij.java")
    plugin("org.intellij.scala", "2024.1.4")
  }
}

Multi-Module Project Structure

When working on a complex plugin, it is often convenient to split the code base into multiple submodules. To avoid pluting submodules with tasks or configurations specific to the root module only, that is, responsible for signing, publishing, or running the plugin, a dedicated subplugin was introduced.

The root module of the IntelliJ-based plugin project is supposed to apply the main Platform plugin as follows:

plugins {
  id("org.jetbrains.intellij.platform") version "2.0.0-rc2"
}

Any other included submodule should utilize the Module instead:

plugins {
  id("org.jetbrains.intellij.platform.module")
}

Last modified: 26 July 2024