IntelliJ Platform Plugin開発にて、compatiblePlugins()を使って、依存するプラグインのバージョンを自動で設定する

JetBrains IntelliJ Platform Plugin Railroads plugin

自作のJetBrains IDE (IntelliJ IDEA / RubyMine)向けプラグイン Railorads にて、JetBrains IDEのバージョンに応じて、Railroadsが依存するRubyプラグインのバージョンを自動設定できるようにしたことから、メモを残します。
https://github.com/thinkAmi/railroads

　
目次

　

自動設定にした背景

JetBrains IDEのプラグイン開発では、 IntelliJ Platform Plugin Templateを使うことで効率よくプラグインを開発できます。
https://github.com/JetBrains/intellij-platform-plugin-template

例えば、Ruby向けのプラグインを開発する際、 gradle.properties の platformPlugins にJetBrainsのRubyプラグインのバージョンを指定するだけです。
https://github.com/JetBrains/intellij-platform-plugin-template/blob/main/gradle.properties

自分の開発したRailroadsプラグインでも、今まで platformPluginsにRubyプラグインのバージョンを指定してきました。

　
また、Railroadsプラグインは幅広いIDEのバージョンをサポートしたいと考えていることから、IDE 2024.2 系以降で使用できるよう pluginSinceBuild に 242 を指定しています。これに合わせて、RubyプラグインのバージョンもIDEのどのバージョン範囲で動作するかを示す Compatibility Range が広いバージョンを指定してきました。

例えば、Railroadsの 0.3.0 では、 242.24807.4 という、IDE 2024.2系であれば互換性が保たれそうなバージョンを指定していました。

　
ただ、最近のRubyプラグインのCompatibility Rangeを見ると、小刻みになっています。そのため、 2024系と2025系をサポートするには platformPlugins にカンマ区切りで複数のバージョンを指定することになります。
https://github.com/JetBrains/intellij-platform-plugin-template/blob/28451c0c0f2b1c3b2b2003c8f099496101d1d261/build.gradle.kts#L45

とはいえ、新しいRubyプラグインのバージョンが出たら毎回 platformPlugins を更新するというのは手間です。できれば、IDEの各バージョンに対応したRubyプラグインのバージョンが自動的に設定されてほしいところです。

　
ところで、自動設定を考えたとき気になるのが「プラグインの依存を管理しているすべてのファイルで定義する必要があるか」です。というのも、プラグインの依存については

  • plugin.xml
  • build.gradle.kt

の2箇所に記載する必要があるためです。

しかし、前者については依存するRubyのバージョンを指定しないことから、今回は「 build.gradle.ktに対して自動設定する」方法を調査すれば良さそうでした。

　

自動設定する方法について調査

自動設定する方法がないかを調べたところ、以下のスレッドに情報がありました。
Resolve plugins from JetBrains Marketplace in the latest compatible version - IntelliJ Platform / Gradle Build Scripts - JetBrains Platform

これによると、 pluginRepository.pluginManager.searchCompatibleUpdates を使うことで、IDEのバージョンに応じたRubyプラグインのバージョンを取得できそうでした。

　
スレッドを追いかけていくと、2025/03/19にIntelliJ Platform Plugin SDKのRecipesサイトにもソースコードが転載したとの投稿がありました。

　
さらに、2025/04/25には、 compatiblePlugin(id) / compatiblePlugins(ids)といったメソッドを実装したという投稿がありました。
https://platform.jetbrains.com/t/resolve-plugins-from-jetbrains-marketplace-in-the-latest-compatible-version/983/7

compatiblePlugin(id) / compatiblePlugins(ids)はドキュメントに記載されているかを見たところ、 Tooling > IntelliJ Platform Gradle Plugin (2.x) > Dependencies Extensionに記載がありました。
https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-dependencies-extension.html#compatible-plugins

これより、2025/10時点では、compatiblePlugin(id) / compatiblePlugins(ids)を使うのが良さそうと考えました。

　

Rubyプラグインへの依存を追加する方法について調査

公式ドキュメントの Plugins | Dependencies Extension | IntelliJ Platform Plugin SDK によると、依存するプラグインの書き方としては以下の2つがありました。

  • Bundled Plugin
  • Non-Bundled Plugins
    • IDEに内蔵されてなく、JetBrains Marketplaceからインストールする必要があるプラグイン
    • プラグインを指定するときは compatiblePlugin() / compatiblePlugins を使う

　
Railroadsプラグインのことを考えたところ、プラグインを動作させる環境により、 Bundled PluginとNon-Bundled Pluginを使い分ける必要がありそうでした。

  • ローカル環境
    • Bundled PluginとNon-Bundled Pluginの両方があり得る
      • ローカルでは、IntelliJ IDEAとRubyMineの両方で動作確認するため
  • GitHub ActionsによるCI環境
    • Bundled PluginとNon-Bundled Pluginのどちらか
      • 本来であれば、IntelliJ IDEAとRubyMineの両方でCIを回したい
      • しかし、ディスクスペースの都合上、両方のすべてのバージョンを指定するとGitHub上のワークスペースの容量が不足し、エラーとなってしまう
      • そこで、IntelliJ IDEAかRubyMineのどちらかでだけ、GitHub ActionsのCIでは動作確認を行う
  • JetBrains Marketplaceの審査時のCI環境
    • Non-Bundled Pluginのみ
      • プラグインの作成者しか閲覧できないJetBrains MarketplaceのVersionsを確認すると、CIでの動作にはIntelliJ IDEAが使われている
        • RubyMineでも動作確認できるが、都度手動で実行する手間があることから、IntelliJ IDEAだけでの動作確認とする

　
ドキュメントを読む限り、 compatiblePlugins() はNon-Bundled Plugin向けの関数のようなので、そこだけ注意して実装します。

　

実装

今回の実装は build.gradle.kt へ addPluginという関数を用意し、 build.gradle.kt が動作する状況により bundledPlugins()と compatiblePlugins()を使い分けることにしました。

どのIDEで動作しているかは intellijPlatform.productInfo.productCode で値が取れるため、それを定数 IntelliJPlatformType.RubyMine.codeと比較することで、RubyMineかどうかを判定しています。
https://plugins.jetbrains.com/docs/intellij/tools-intellij-platform-gradle-plugin-types.html#IntelliJPlatformType

あとは、

  • RubyMineで使われている場合、 bundledPlugins() を使う
  • それ以外で使われている場合、 compatiblePlugins()を使う

という実装になります。

// 関数の定義
fun IntelliJPlatformDependenciesExtension.addPlugin(vararg pluginIds: String) {
    // For RubyMine, since the Ruby plugin is bundled with the IDE, use bundledPlugins().
    bundledPlugins(provider {
        pluginIds.filter {
            intellijPlatform.productInfo.productCode == IntelliJPlatformType.RubyMine.code
        }
    })

    // For IntelliJ IDEA, since the Ruby plugin is not bundled with the IDE,
    // use compatiblePlugin() to add a Ruby plugin with compatibility considerations.
    compatiblePlugins(provider {
        pluginIds.filter {
            intellijPlatform.productInfo.productCode == IntelliJPlatformType.IntellijIdeaUltimate.code
        }
    })
}

// 実際に使うところ
dependencies {
    intellijPlatform {
        // ...
        addPlugin("org.jetbrains.plugins.ruby")
        // ...

　
動作確認したところ、いずれの環境でも、IDEバージョンごとに適切なRubyプラグインのバージョンが指定されました。

これにより、 gradle.propertiesにRubyプラグインのバージョンを指定する必要がなくなったため、メンテナンスが非常に楽になりました。

　

ソースコード

Railroadsのリポジトリにあります。
https://github.com/thinkAmi/railroads

実際に対応したときのプルリクはこちら。ちなみに、このプルリクでは他にも色々対応したため、関係ないコードも含まれてしまっています。
https://github.com/thinkAmi/railroads/pull/63