diff --git a/topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_plugins.md b/topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_plugins.md index 8edf300b6..eca16d565 100644 --- a/topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_plugins.md +++ b/topics/appendix/tools/intellij_platform_gradle_plugin/tools_intellij_platform_gradle_plugin_plugins.md @@ -6,74 +6,51 @@ -The IntelliJ Platform Gradle Plugin consists of multiple subplugins which can be applied in bundles ([](#platform) or [](#module)) or separately. +The IntelliJ Platform Gradle Plugin consists of subplugins which should be applied depending on the project structure. Subplugins architecture allows applying a subset of features, e.g., to provide the IntelliJ Platform dependency to a project submodule without creating unnecessary tasks. -> Plugins depend on each other. -> -> When applying the [](#module) plugin, there is no need for manual applying the [](#build) plugin. - The following chart describes dependencies between plugins provided with the IntelliJ Platform Gradle Plugin. -The plugins highlighted in bold are recommended for most of the cases when creating a plugin for IntelliJ-based IDEs. ```mermaid -flowchart LR - Platform("Platform") - Module("Module") - Settings("Settings") - Migration +flowchart TB - Base - Build - Test - Verify - Run - Publish - - Build --> Base - Publish --> Build - Run --> Build - Test --> Build - Verify --> Build - Module --> Test & Verify - Platform --> Publish & Run & Module - - subgraph ALL ["` `"] - Settings - Platform - Module - Migration + subgraph SETTINGS_LEVEL ["
settings.gradle.kts
"] + Settings("Settings") end + subgraph PROJECT_LEVEL ["
build.gradle.kts
"] + Platform("Platform") + Module("Module") + Migration + Base + end + + Module --> Base + Platform --> Module & Base Migration --> Platform - Migration ~~~ Build click Platform "#platform" click Module "#module" click Settings "#settings" click Migration "#migration" click Base "#base" - click Build "#build" - click Test "#test" - click Verify "#verify" - click Run "#run" - click Publish "#publish" style Platform stroke-width: 3px style Module stroke-width: 3px style Settings stroke-width: 3px - style ALL fill:transparent,stroke:transparent + style SETTINGS_LEVEL fill:transparent,stroke:#666,stroke-dasharray: 10 10 + style PROJECT_LEVEL fill:transparent,stroke:#666,stroke-dasharray: 10 10 ``` + ## Platform **Plugin ID: `org.jetbrains.intellij.platform`** -This is a top-level plugin that applies all project-level subplugins that bring the fully flagged tooling for plugin development for IntelliJ-based IDEs. - -This plugin should be used in most cases when working with a single-module project: +This is a top-level plugin that applies all the tooling for plugin development for IntelliJ-based IDEs. +It should be used only with the root module (for submodules, see [](#module)). build.gradle.kts ```kotlin @@ -82,21 +59,14 @@ plugins { } ``` -Included plugins: -- [](#base) -- [](#build) -- [](#test) -- [](#verify) -- [](#run) -- [](#publish) ## Module **Plugin ID: `org.jetbrains.intellij.platform.module`** -This top-level plugin applies a smaller set of subplugins required for providing required dependencies and build/test tasks for a submodule when working on a plugin for IntelliJ-based IDEs in a multi-module architecture. +This plugin applies a smaller set of functionalities for compiling and testing submodules when working in a multi-module architecture. -Comparing to the main plugin, it doesn't contain tasks related to publishing or running the IDE for testing purposes. +Compared to the main plugin, it doesn't contain tasks related to publishing or running the IDE for testing purposes. settings.gradle.kts @@ -106,30 +76,6 @@ rootProject.name = "..." include(":submodule") ``` -build.gradle.kts - -```kotlin -plugins { - id("org.jetbrains.intellij.platform") version "%intellij-platform-gradle-plugin-version%" -} - -repositories { - mavenCentral() - - intellijPlatform { - defaultRepositories() - } -} - -dependencies { - implementation(project(":submodule")) - - intellijPlatform { - intellijIdeaCommunity("%ijPlatform%") - } -} -``` - submodule/build.gradle.kts ```kotlin @@ -152,19 +98,40 @@ dependencies { } ``` -Included plugins: -- [](#base) -- [](#build) -- [](#test) -- [](#verify) +build.gradle.kts + +```kotlin +plugins { + id("org.jetbrains.intellij.platform") version "%intellij-platform-gradle-plugin-version%" +} + +repositories { + mavenCentral() + + intellijPlatform { + defaultRepositories() + } +} + +dependencies { + intellijPlatform { + intellijIdeaCommunity("%ijPlatform%") + pluginModule(implementation(project(":submodule"))) + } +} +``` + +Note that the `:submodule` is added both to the `implementation` configuration and `intellijPlatformPluginModule` using the `pluginModule` helper method. +This guarantees that the submodule content will be merged into the main plugin Jar file. + ## Settings **Plugin ID: `org.jetbrains.intellij.platform.settings`** -If repositories are defined within the settings.gradle.kts using the `dependencyResolutionManagement` Gradle, make sure to include the Settings plugin in settings.gradle.kts. +If you define project repositories within the settings.gradle.kts using the `dependencyResolutionManagement`, make sure to include the Settings plugin in settings.gradle.kts. -See [](tools_intellij_platform_gradle_plugin.md#configuration.dependencyResolutionManagement) for more details. +This approach allows for ommiting the `repositories {}` definition in the build.gradle.kts files. See [](tools_intellij_platform_gradle_plugin.md#configuration.dependencyResolutionManagement) for more details. settings.gradle.kts @@ -200,10 +167,9 @@ plugins { } dependencies { - implementation(project(":submodule")) - intellijPlatform { intellijIdeaCommunity("%ijPlatform%") + pluginModule(implementation(project(":submodule"))) } } ``` @@ -226,10 +192,10 @@ dependencies { **Plugin ID: `org.jetbrains.intellij.platform.migration`** -The Migration plugin is designed to assist in upgrading projects using Gradle IntelliJ Plugin **1.x**. +The Migration plugin is designed to assist in upgrading projects that use Gradle IntelliJ Plugin **1.x** to the **2.x** version. To prevent Gradle failing due to breaking changes, the `org.jetbrains.intellij.platform.migration` plugin was introduced to fill missing gaps and provide migration hints. -It loads the [](#platform) plugin with additional mocks and checks applied — after the successful migration, it is recommended to replace the `org.jetbrains.intellij.platform.migration` identifier with `org.jetbrains.intellij.platform`. +It loads the [](#platform) plugin with additional mocks and checks applied — after the successful migration, the `org.jetbrains.intellij.platform.migration` identifier shoud be replaced with `org.jetbrains.intellij.platform`. See [](tools_intellij_platform_gradle_plugin_migration.md) for more details. @@ -237,94 +203,27 @@ See [](tools_intellij_platform_gradle_plugin_migration.md) for more details. **Plugin ID: `org.jetbrains.intellij.platform.base`** -Sets up all the custom configurations and transformers needed to manage the IntelliJ Platform dependency, JetBrains Runtime, CLI tools, and other plugins when they're added as dependencies. +Prepares all the custom configurations, transformers, and base tasks needed to manage the IntelliJ Platform dependency, JetBrains Runtime, CLI tools, and others. -It also introduces the [](tools_intellij_platform_gradle_plugin_extension.md) to the build.gradle.kts file along with [](tools_intellij_platform_gradle_plugin_dependencies_extension.md) and [](tools_intellij_platform_gradle_plugin_repositories_extension.md) to help preconfiguring project dependencies: +It also introduces the [](tools_intellij_platform_gradle_plugin_extension.md) to the build.gradle.kts file along with [](tools_intellij_platform_gradle_plugin_dependencies_extension.md) and [](tools_intellij_platform_gradle_plugin_repositories_extension.md) to help preconfigure project dependencies: ```kotlin repositories { ... - intellijPlatform { - // Repositories Extension - } + // Repositories Extension + intellijPlatform { ... } } dependencies { ... - intellijPlatform { - // Dependencies Extension - } + // Dependencies Extension + intellijPlatform { ... } } -intellijPlatform { - // IntelliJ Platform Extension -} +// IntelliJ Platform Extension +intellijPlatform { ... } ``` -Plugin also introduces a task listener which allows for creating custom tasks decorated with [](tools_intellij_platform_gradle_plugin_task_awares.md). - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#initializeIntelliJPlatformPlugin) -- [](tools_intellij_platform_gradle_plugin_tasks.md#printBundledPlugins) -- [](tools_intellij_platform_gradle_plugin_tasks.md#printProductsReleases) - -## Build - -**Plugin ID: `org.jetbrains.intellij.platform.build`** - -Registers and preconfigures tasks responsible for patching, instrumenting, and building the plugin. - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#buildPlugin) -- [](tools_intellij_platform_gradle_plugin_tasks.md#buildSearchableOptions) -- [](tools_intellij_platform_gradle_plugin_tasks.md#instrumentCode) -- [](tools_intellij_platform_gradle_plugin_tasks.md#jarSearchableOptions) -- [](tools_intellij_platform_gradle_plugin_tasks.md#patchPluginXml) -- [](tools_intellij_platform_gradle_plugin_tasks.md#prepareSandbox) - -## Publish - -**Plugin ID: `org.jetbrains.intellij.platform.publish`** - -Adds tasks responsible for signing and publishing the final plugin archive to JetBrains Marketplace. - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#signPlugin) -- [](tools_intellij_platform_gradle_plugin_tasks.md#publishPlugin) - -## Run - -**Plugin ID: `org.jetbrains.intellij.platform.run`** - -Registers the task used for running the local instance of the IntelliJ Platform used for development. - -It allows introducing custom tasks, so it is possible to run a plugin against various IDEs during the development process. - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#runIde) - -## Test - -**Plugin ID: `org.jetbrains.intellij.platform.test`** - -Preconfigures the existing `test` task to make the plugin testing possible (unit tests, UI tests, performance tests). -In addition, it preconfigures the customizable `TestIdeTask` class, so it is possible to register multiple `test*` tasks for running tests against different IDEs. - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#prepareTest) -- [](tools_intellij_platform_gradle_plugin_tasks.md#testIdePerformance) -- [](tools_intellij_platform_gradle_plugin_tasks.md#testIdeUi) - -## Verify - -**Plugin ID: `org.jetbrains.intellij.platform.verify`** - -Introduces various verification tasks that run checks against project configuration, plugin.xml file, signature check, or execute the IntelliJ Plugin Verifier tool. - -Included tasks: -- [](tools_intellij_platform_gradle_plugin_tasks.md#verifyPluginProjectConfiguration) -- [](tools_intellij_platform_gradle_plugin_tasks.md#verifyPlugin) -- [](tools_intellij_platform_gradle_plugin_tasks.md#verifyPluginSignature) -- [](tools_intellij_platform_gradle_plugin_tasks.md#verifyPluginStructure) +The plugin also introduces a task listener which allows for creating custom tasks decorated with [](tools_intellij_platform_gradle_plugin_task_awares.md).