IntelliJ Platform Gradle Plugin 2.0 Is Out!

Jakub Chrzanowski

Version 2.0 of the IntelliJ Platform Gradle Plugin is now available! Previously called the Gradle IntelliJ Plugin, this updated plugin for the Gradle build system simplifies the configuration of environments for building, testing, verifying, and publishing plugins for IntelliJ-based IDEs. Redesigned and rewritten, it addresses community-reported issues and feature requests from previous versions.

The path to 2.0

The project to create this plugin began in 2015 with the goal of simplifying the development and testing of plugins for JetBrains IDEs. Initially, it was developed in Groovy, which remained the primary language for the first six years, during the 0.x releases.

In May 2021, version 1.0 was released, marking a complete migration to Kotlin. This transition addressed multiple issues thanks to Kotlin’s strong typing and null safety, though the core architecture remained unchanged. Around the same time, Gradle announced the configuration and build cache mechanisms. Those improvements in the Gradle build system highlighted fundamental weaknesses in the Gradle IntelliJ Plugin, revealing that maintaining it without workarounds was no longer viable.

In the summer of 2023, we started adjusting the core functionality – the beginning of a challenging, year-long journey towards the release of version 2.0.

New strategy for repository and dependency management

One of our main goals was fixing an architectural problem in the 1.x versions, which applied repositories and dependencies implicitly during task runtime. This approach had numerous side effects, addressed in the new 2.0 release.

Repositories defined explicitly

The old version tried to keep configuration simple by adding all necessary repositories when the IntelliJ Platform dependency was resolved. The fixed repository list made Gradle search for dependencies in locations irrelevant to project needs or even unavailable for resolving.

repositories {
    mavenCentral()

    intellijPlatform {
        // use the recommended repository list
        defaultRepositories()

        // or explicit set
        jetbrainsIdeInstallers()
        releases()
        localPlatformArtifacts()
        intellijDependencies()
        // ...
    }

    maven("...") {
       authentication {
           // ...
       }
    }
}

The current solution allows using a recommended set of repositories or using only specific elements whenever you don’t need others or decide to replace them with a custom artifactory.

All resources as dependencies

The solution present in 1.x requested dependencies and tools in the task execution phase – this prevented Gradle from caching the project configuration or task output. This could also result in unsatisfied requests when working in environments with limited network capacity.

With the 2.x release, everything required for building, testing, and verifying the plugin is defined as a dependency.

The new approach requires explicit declarations of the IntelliJ Platform and all other dependencies:

dependencies {
   testImplementation(libs.junit)

   intellijPlatform {
       intellijIdeaCommunity("2023.2.7")
       instrumentationTools()
       pluginVerifier()
       testFramework(TestFrameworkType.Platform)
   }
}

Relying fully on the Gradle approach for managing dependencies makes it possible to involve caching for every requested resource and avoid resolving dependencies eagerly.

Advanced dependency management

Changes applied to repository and dependency configuration allow involving advanced Gradle techniques, like declaring centralized repositories. All of the project repositories can now be specified within the settings.gradle.kts file, which applies them to all declared project modules.

import org.jetbrains.intellij.platform.gradle.extensions.intellijPlatform
      
plugins {
   id("org.jetbrains.intellij.platform.settings") version "2.0.0"
}


dependencyResolutionManagement {
   repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS

   repositories {
       mavenCentral()

       intellijPlatform {
           defaultRepositories()
       }
   }
}

From now on, the repositories {} block in any build.gradle.kts  is redundant.

Powerful DSL

The new intellijPlatform {} extension replaces the old intellij {} and facilitates the detailed configuration of all relevant plugin configuration values, as well as signing, verifying, and publishing plugins:

intellijPlatform {
   pluginConfiguration {
       version = providers.gradleProperty("pluginVersion")
       name = "My Awesome Plugin"

       description = ...
       changeNotes = ...

       ideaVersion {
           sinceBuild = "223"
           untilBuild = "242.*"
       }
   }

   signing {
       // ...
   }

   publishing {
       // ...
   }

   pluginVerification {
       // ...
   }
}

All extension properties and helper methods accept values passed either eagerly or lazily wrapped with Provider, which is available in the Gradle API. However, the simple property assignment in the Kotlin DSL, introduced in Gradle 8.2, keeps this change transparent.

In addition to the root intellijPlatform {} extension, new extensions have been introduced for the repositories {} and dependencies {} blocks. Each of these extensions provides dedicated helpers for applying repositories and dependencies related to the development of plugins for the IntelliJ Platform. This approach offers full control over what is applied to the configuration.

Improved testing experience

The changes in how the IntelliJ Platform and dependencies in bundled and external plugins are applied to the project have opened up new possibilities in testing. You can now create custom run and test tasks targeting different IntelliJ Platform types and versions or plugin sets without changing the IntelliJ Platform version and type used to build the plugin.

Using the new intellijPlatformTesting {} extension, you can register tasks of various types and purposes:

val runPhpStorm by intellijPlatformTesting.runIde.registering {
   type = IntelliJPlatformType.PhpStorm
   version = "2024.2"

   plugins {
       plugin("pluginId", "1.0.0")
       disablePlugin("bundledPluginId")
   }
}

The code above creates a new runPhpStorm task for running PhpStorm 2024.2 locally for manual testing purposes with the pluginId installed from JetBrains Marketplace and the bundledPluginId plugin disabled.

This approach helps with running manual or automated tests for different scenarios, such as ones where bundled plugins are disabled or optional plugins are installed.

Multi-project builds support

To address previous issues with multi-project builds, the IntelliJ Platform Gradle Plugin has been restructured into several sub-plugins. These sub-plugins can be applied selectively based on the architecture of your project.

This modular approach allows for the application of specific features, such as providing IntelliJ Platform dependencies to a project submodule, without introducing unnecessary tasks.

For projects using IntelliJ-based IDEs, the main module should always include the org.jetbrains.intellij.platform plugin in its configuration file. In contrast, other submodules should utilize the org.jetbrains.intellij.platform.module plugin. This ensures the proper export of output archives and optimizes the build process. For submodules that require only access to the IntelliJ Platform dependency, the org.jetbrains.intellij.platform.base plugin should be applied.

New name and requirements

This release brings major configuration and conceptual changes. In order to help distinguish the new configuration from the old one, version 2.0 of the plugin has a new ID: org.jetbrains.intellij.platform.

Another reason for the name change was confusion of the Gradle IntelliJ Plugin with the Gradle plugin, which is bundled in IntelliJ IDEA and offers actual Gradle integration features. The name “IntelliJ Platform Gradle Plugin” highlights that it is the “IntelliJ Platform Plugin” for the “Gradle” build system.

To make it possible to introduce solutions that address almost all of the issues reported over the last few years, it was necessary to limit support for older versions of the IntelliJ Platform, Gradle, and Java Runtime. IntelliJ Platform Gradle Plugin 2.0 requires the following minimal versions:

• IntelliJ Platform – 2022.3
• Gradle – 8.2
• Java Runtime – 17

Those constraints helped us focus more on recent IntelliJ Platform versions and developer environments, allowing us to close over 100 reported issues, improve project quality, and cover it with more unit and integration tests.

The importance of updating

IntelliJ IDEA 2024.2 introduces changes to the layout of IntelliJ Platform modules. To use version 2024.2+ of an IntelliJ-based IDE for building plugins, migrating to version 2.0 of the IntelliJ Platform Gradle Plugin is essential, as the new layout changes cannot be easily backported to the 1.x branch.

Additionally, Android Studio 2024.1 on macOS has discontinued the use of ZIP archives and now only provides DMG installers, which the 1.x version of the Gradle plugin cannot handle.

As of the 2.0 release, the development of 1.x is now frozen and no more updates are planned.

Next steps

To start using version 2.0 of the IntelliJ Platform Gradle Plugin, visit the documentation pages at IntelliJ Platform SDK | Tooling | IntelliJ Platform Gradle Plugin 2.x, where you will find a proper introduction to all of the new features and changes, a migration guide, and examples of various configurations you may be interested in.

For projects created with the IntelliJ Platform Plugin Template, we advise taking a look at the 2.0.0 pull request applied on top of the obsolete Gradle IntelliJ Plugin 1.x configuration: https://github.com/JetBrains/intellij-platform-plugin-template/pull/458/files

If you have any issues or requests, please submit them to our GitHub Issues page or the JetBrains Platform Slack.

To submit questions or suggestions related to the documentation, please use the feedback form at the bottom of the article.

Subscribe to JetBrains Platform updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!