IntelliJ Platform Gradle Plugin: JetBrains Runtime (#1306)

IntelliJ Platform Gradle Plugin: JetBrains Runtime

.github/scripts/android_studio_releases.main.kts

@@ -57,7 +57,7 @@ fun List<Item>.renderTable() = """
   | Release Name | Channel | Release Date | Version | IntelliJ IDEA Version |
   |--------------|:-------:|--------------|---------|-----------------------|
 """ + sortedByDescending { it.version.toLooseVersion() }.joinToString("\n") {
-  val name = it.name.removePrefix("Android Studio").trim().replace("|", "\\|")
+  val name = it.name.removePrefix("Android Studio").trim().replace("|", "&#124;")
   val channel = it.channel.run { "![$this][${this.lowercase()}]" }
   val date = it.date
   val version = "**${it.version}**<p>${it.build}</p>"

ijs.tree

@@ -426,6 +426,7 @@
       <toc-element topic="tools_intellij_platform_gradle_plugin_task_awares.md"/>
       <toc-element topic="tools_intellij_platform_gradle_plugin_types.md"/>
       <toc-element topic="tools_intellij_platform_gradle_plugin_gradle_properties.md"/>
+      <toc-element topic="tools_intellij_platform_gradle_plugin_jetbrains_runtime.md"/>
       <toc-element topic="tools_intellij_platform_gradle_plugin_migration.md"/>
       <toc-element topic="tools_intellij_platform_gradle_plugin_faq.md" toc-title="Frequently Asked Questions"/>
     </toc-element>

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_dependencies_extension.md

@@ -108,6 +108,7 @@ targeted plugin is _bundled_ with the Target Platform or not.
 | `plugin(id, version, channel)` | Adds a dependency on a plugin for IntelliJ Platform.                                                                                |
 | `plugin(notation)`             | Adds a dependency on a plugin for IntelliJ Platform using a string notation:<p>`pluginId:version` or `pluginId:version@channel`</p> |
 | `plugins(notations)`           | Adds dependencies on plugins for IntelliJ Platform using a string notation:<p>`pluginId:version` or `pluginId:version@channel`</p>  |
+| `localPlugin(localPath)`       | Adds a dependency on a local IntelliJ Platform plugin. Accepts path or a dependency on another module.                              |
 
 See also:
 
@@ -162,14 +163,16 @@ See also:
 
 ## Java Runtime
 
-Using the `jetbrainsRuntime()` dependency helper, it is possible to load a custom version of JetBrains Runtime.
+Using the `jetbrainsRuntime()` or `jetbrainsRuntimeExplicit()` dependency helpers, it is possible to load a custom version of JetBrains Runtime.
 However, it is recommended to rely on the runtime bundled within the IntelliJ Platform dependency, if present.
 
 | Function                                                  | Description                                                                                                                                                                                                                     |
-|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| <p>`jetbrainsRuntime(version, variant, architecture)`</p><p>`jetbrainsRuntime(explicitVersion)`</p> | Adds a dependency on [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). |
+| <p>`jetbrainsRuntime()`</p>                               | Adds a dependency on [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance) in version obtained with the current IntelliJ Platform if resolved from IntelliJ Maven Repository. |
+| <p>`jetbrainsRuntime(version, variant, architecture)`</p> | Adds a dependency on [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).                                                                                                   |
+| <p>`jetbrainsRuntimeExplicit(explicitVersion)`</p>        | Adds a dependency on [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance) in explicit version.                                                                               |
 
-See the [JetBrains Runtime releases page](https://github.com/JetBrains/JetBrainsRuntime/releases) for the list of available releases.
+See [](tools_intellij_platform_gradle_plugin_jetbrains_runtime.md) for more details.
 
 ## Code Instrumentation
 

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_jetbrains_runtime.md

@@ -0,0 +1,136 @@
+<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+
+# JetBrains Runtime (JBR)
+
+<link-summary>The IntelliJ Platform Gradle Plugin requires JetBrains Runtime (JBR), which can be provided in multiple ways.</link-summary>
+
+<include from="tools_intellij_platform_gradle_plugin.md" element-id="Beta_Status"/>
+<include from="tools_intellij_platform_gradle_plugin.md" element-id="faq"/>
+
+JetBrains Runtime (JBR) is a custom version of OpenJDK, specifically optimized for IntelliJ-based IDEs. It supports enhanced class redefinition (DCEVM), includes the Java Chromium Embedded Framework (JCEF), and improves aspects such as font rendering and keyboard support, thereby enhancing overall performance.
+IDEs built on the IntelliJ Platform rely on JBR for running.
+Hence, when developing plugins using the IntelliJ Platform Gradle Plugin, it's essential to have JBR provided.
+
+For the best experience, it is recommended to rely on JBR bundled with the IntelliJ Platform used for development.
+If one is not available, i.e., when targeting IntelliJ Platform snapshot or nightly releases, there are other ways available for providing JetBrains Runtime in a required version or variant.
+
+## Bundled (Default)
+
+IDE releases provided with JetBrains CDN (download.jetbrains.com) are OS-specific and contain JetBrains Runtime (JBR) already bundled within the archive.
+This is the recommended way for developing a plugin, as it comes in exactly the same version as JetBrains IDEs delivered to users.
+
+To use this approach, no extra steps are required but declare the IntelliJ Platform, see: [](tools_intellij_platform_gradle_plugin_dependencies_extension.md#target-platforms).
+
+## Obtained with IntelliJ Platform from Maven
+
+If the IntelliJ Platform is resolved with the IntelliJ Maven Repository, it has no JetBrains Runtime (JBR) bundled.
+In such a case, it is necessary to provide it in the suitable version with the version read from the <path>[intellijPlatform]/dependencies.txt</path> file.
+
+This can be easily achieved by using the `jetbrainsRuntime()` repository helper pointing to [JetBrains Runtime GitHub Releases](https://github.com/JetBrains/JetBrainsRuntime/releases/) and dependency helper with no arguments provided:
+
+```kotlin
+repositories {
+  mavenCentral()
+  intellijPlatform {
+    defaultRepositories()
+    jetbrainsRuntime()
+    // ...
+  }
+}
+
+dependencies {
+  intellijPlatform {
+    intellijIdeaCommunity("%ijPlatform%")
+
+    jetbrainsRuntime()
+
+    // ...
+  }
+}
+```
+
+## Declared Explicitly
+
+It is possible to explicitly specify JetBrains Runtime version, variant, or exact build with:
+
+```kotlin
+repositories {
+  mavenCentral()
+  intellijPlatform {
+    defaultRepositories()
+    jetbrainsRuntime()
+    // ...
+  }
+}
+
+dependencies {
+  intellijPlatform {
+    intellijIdeaCommunity("%ijPlatform%")
+
+    jetbrainsRuntime(version, variant, architecture)
+    // or
+    jetbrainsRuntimeExplicit(explicitVersion)
+
+    // ...
+  }
+}
+```
+
+Provided `version`, `variant`, and `architecture` parameters along with the `explicitVersion` are used to resolve the JetBrains Runtime archives published on [GitHub Releases](https://github.com/JetBrains/JetBrainsRuntime/releases/) page.
+
+To correctly understand the pattern, refer to the archive names in format:
+```
+jbr_[prefix]-[jdk]-[os]-[arch]-b[build].tar.gz
+```
+e.g.:
+```
+jbr_jcef-21.0.3-osx-aarch64-b446.1.tar.gz
+```
+which can be split into the following parts:
+
+- `prefix` = `jcef`
+- `jdk` = `21.0.3`
+- `os` = `osx`
+- `arch` = `aarch64`
+- `build` = `446.1`
+
+Note that the `version` parameter is actually a combination of JDK and build numbers in format `[jdk]b[build]`.
+
+To resolve the `jbr_jcef-21.0.3-osx-aarch64-b446.1.tar.gz` archive, you can use:
+- `jetbrainsRuntime("21.0.3b446.1", "osx", "aarch64")`
+- `jetbrainsRuntime("21.0.3b446.1")` (`os` and `architecture` are by default resolved with the current environment)
+- `jetbrainsRuntimeExplicit("jbr_jcef-21.0.3-osx-aarch64-b446.1")`
+
+See the [JetBrains Runtime releases page](https://github.com/JetBrains/JetBrainsRuntime/releases) for the list of available releases.
+
+## Foojay Toolchains Plugin
+
+Since Gradle `8.4`, it is possible to specify JetBrains as a known JVM vendor and instruct Gradle to search for JetBrains Runtime within available toolchains (see [Toolchains for JVM projects](https://docs.gradle.org/current/userguide/toolchains.html)).
+
+Along with the [Foojay Toolchains Plugin](https://github.com/gradle/foojay-toolchains), Gradle can resolve JetBrains Runtime from the remote repository if the suitable JVM is not present:
+
+<path>build.gradle.kts</path>
+```kotlin
+kotlin {
+  jvmToolchain {
+    languageVersion = JavaLanguageVersion.of(17)
+    vendor = JvmVendorSpec.JETBRAINS
+  }
+}
+```
+
+<path>settings.gradle.kts</path>
+```kotlin
+plugins {
+    id("org.gradle.toolchains.foojay-resolver-convention") version "..."
+}
+```
+
+Please note that the latest available JetBrains Runtime release is always resolved, which may lead to unexpected behaviors.
+
+## Project SDK
+
+When building or running a project directly from the IDE, it is possible to specify JetBrains Runtime in Project Settings as a Project SDK.
+
+Provided JBR will be eventually resolved and passed to Gradle tasks for running.
+However, this setting is ignored when running a project directly from the command line or CI.

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_task_awares.md

@@ -167,6 +167,7 @@ tasks {
 | `plugins(notations)`           | Adds dependencies on plugins for a custom IntelliJ Platform using a string notation:<p>`pluginId:version` or `pluginId:version@channel`</p>  |
 | `disablePlugin(id)`            | Disables the specific plugin with its ID.                                                                                                    |
 | `disablePlugins(ids)`          | Disables specific plugins with the list of their IDs.                                                                                        |
+| `localPlugin(path)`            | Adds a dependency on a local IntelliJ Platform plugin. Accepts path or a dependency on another module.                                       |
 
 
 ## `IntelliJPlatformVersionAware`
@@ -343,7 +344,7 @@ Type
 
 <tldr>
 
-**Depends on**: [`AutoReloadAware`](#AutoReloadAware), [`CoroutinesJavaAgentAware`](#CoroutinesJavaAgentAware), [`PluginAware`](#PluginAware), [`RuntimeAware`](#RuntimeAware), [`SandboxAware`](#SandboxAware), [`SplitModeAware`](#SplitModeAware)
+**Depends on**: [`AutoReloadAware`](#AutoReloadAware), [`CoroutinesJavaAgentAware`](#CoroutinesJavaAgentAware), [`PluginAware`](#PluginAware), [`RuntimeAware`](#RuntimeAware), [`SandboxAware`](#SandboxAware)
 
 **Inherited by**: [`buildSearchableOptions`](tools_intellij_platform_gradle_plugin_tasks.md#buildSearchableOptions), [`runIde`](tools_intellij_platform_gradle_plugin_tasks.md#runIde), [`testIdePerformance`](tools_intellij_platform_gradle_plugin_tasks.md#testIdePerformance), [`testIdeUi`](tools_intellij_platform_gradle_plugin_tasks.md#testIdeUi)
 
@@ -444,10 +445,10 @@ Type
 : `Property<String>`
 
 
-### `sandboxContainerDirectory`
+### `sandboxDirectory`
-{#SandboxAware-sandboxContainerDirectory}
+{#SandboxAware-sandboxDirectory}
 
-The container for all sandbox-related directories.
+The directory containing content read and produced by the running IDE.
 
 The directory name depends on the platform type and version currently used for running a task.
 
@@ -459,7 +460,7 @@ Type
 ### `sandboxConfigDirectory`
 {#SandboxAware-sandboxConfigDirectory}
 
-A configuration directory located within the [`sandboxContainerDirectory`](#SandboxAware-sandboxContainerDirectory).
+A configuration directory located within the [`sandboxDirectory`](#SandboxAware-sandboxDirectory).
 
 {style="narrow"}
 Type
@@ -469,7 +470,7 @@ Type
 ### `sandboxPluginsDirectory`
 {#SandboxAware-sandboxPluginsDirectory}
 
-A plugins directory located within the [`sandboxContainerDirectory`](#SandboxAware-sandboxContainerDirectory).
+A plugins directory located within the [`sandboxDirectory`](#SandboxAware-sandboxDirectory).
 
 {style="narrow"}
 Type
@@ -479,7 +480,7 @@ Type
 ### `sandboxSystemDirectory`
 {#SandboxAware-sandboxSystemDirectory}
 
-A system directory located within the [`sandboxContainerDirectory`](#SandboxAware-sandboxContainerDirectory).
+A system directory located within the [`sandboxDirectory`](#SandboxAware-sandboxDirectory).
 
 {style="narrow"}
 Type
@@ -489,7 +490,7 @@ Type
 ### `sandboxLogDirectory`
 {#SandboxAware-sandboxLogDirectory}
 
-A log directory located within the [`sandboxContainerDirectory`](#SandboxAware-sandboxContainerDirectory).
+A log directory located within the [`sandboxDirectory`](#SandboxAware-sandboxDirectory).
 
 {style="narrow"}
 Type
@@ -543,7 +544,7 @@ Type
 
 <tldr>
 
-**Inherited by**: [`RunnableIdeAware`](#RunnableIdeAware), [`prepareSandbox`](tools_intellij_platform_gradle_plugin_tasks.md#prepareSandbox)
+**Inherited by**: [`prepareSandbox`](tools_intellij_platform_gradle_plugin_tasks.md#prepareSandbox), [`runIde`](tools_intellij_platform_gradle_plugin_tasks.md#runIde)
 
 **Sources**: [`SplitModeAware`](%gh-ijpgp-master%/src/main/kotlin/org/jetbrains/intellij/platform/gradle/tasks/aware/SplitModeAware.kt)
 

topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_tasks.md

@@ -1465,6 +1465,19 @@ Default value
 : The `org.jetbrains.kotlinx:kotlinx-coroutines` dependency presence
 
 
+### `hasModulePlugin`
+{#verifyPluginProjectConfiguration-hasModulePlugin}
+
+Defines if the current module is a main project or imported module, which uses [](tools_intellij_platform_gradle_plugin_plugins.md#module) plugin.
+
+{style="narrow"}
+Type
+: `Property<Boolean>`
+
+Default value
+: The [](tools_intellij_platform_gradle_plugin_plugins.md#module) plugin presence
+
+
 ## `verifyPluginSignature`
 {#verifyPluginSignature}