From 43f08f73382c331cde7fb9b2d9271a10fb86e754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20C=C3=A9bron?= Date: Wed, 2 Oct 2024 18:06:43 +0200 Subject: [PATCH] dev_alternate_products.md: restructure for Gradle 1/2 --- .../products/androidstudio/android_studio.md | 2 +- topics/products/clion/clion.md | 2 +- topics/products/datagrip/data_grip.md | 2 +- topics/products/dev_alternate_products.md | 44 +++++++++++-------- topics/products/goland/goland.md | 4 +- topics/products/idea/idea.md | 2 +- topics/products/phpstorm/phpstorm.md | 4 +- topics/products/pycharm/pycharm.md | 2 +- topics/products/webstorm/webstorm.md | 2 +- 9 files changed, 35 insertions(+), 29 deletions(-) diff --git a/topics/products/androidstudio/android_studio.md b/topics/products/androidstudio/android_studio.md index c38856148..0610c1e91 100644 --- a/topics/products/androidstudio/android_studio.md +++ b/topics/products/androidstudio/android_studio.md @@ -78,7 +78,7 @@ dependencies { {collapsible="true" default-state="collapsed"} -The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](dev_alternate_products.md#configuring-gradle-build-script-to-target-products-other-than-intellij-idea) section. +The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](dev_alternate_products.md#gradle1) section. The particular example in that section discusses configuring a plugin project for PhpStorm, so the details for an Android Studio plugin project are reviewed here. Here are the steps to configure the Gradle build script for developing a plugin to target Android Studio: diff --git a/topics/products/clion/clion.md b/topics/products/clion/clion.md index 22a24fec2..8d88ec75d 100644 --- a/topics/products/clion/clion.md +++ b/topics/products/clion/clion.md @@ -51,7 +51,7 @@ dependencies { -The configuration of CLion plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). +The configuration of CLion plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. diff --git a/topics/products/datagrip/data_grip.md b/topics/products/datagrip/data_grip.md index 7fe67b990..19f2dbdec 100644 --- a/topics/products/datagrip/data_grip.md +++ b/topics/products/datagrip/data_grip.md @@ -48,7 +48,7 @@ dependencies { -The configuration of DataGrip plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). +The configuration of DataGrip plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. diff --git a/topics/products/dev_alternate_products.md b/topics/products/dev_alternate_products.md index 84cd274ea..8f8749dfe 100644 --- a/topics/products/dev_alternate_products.md +++ b/topics/products/dev_alternate_products.md @@ -4,45 +4,49 @@ Configuring plugin projects for targeting IntelliJ Platform-based IDEs other than IntelliJ IDEA. - - Plugin projects can target any (custom) IDEs, as long as the products are based on the [IntelliJ Platform](intellij_platform.md). Such plugins are developed much like plugin projects that target IntelliJ IDEA. -Project configuration attributes common to projects targeting products other than IntelliJ IDEA are described on this page. -Details particular to an IntelliJ Platform-based product are described on the individual product pages in _Product Specific_. - -All the Gradle configuration attributes described here are discussed in-depth on the [](configuring_plugin_project.md) and the [](tools_gradle_intellij_plugin.md). - -## Getting Started +Modifications are required to the project's Gradle build script and [plugin.xml](plugin_configuration_file.md) files, as described below +and on the individual product pages in _Product Specific_. +The Gradle build script is modified to specify the target product, determining the APIs available to the plugin. +The plugin.xml file is modified to declare the plugin's dependencies on plugins and modules. + +## IntelliJ Platform Gradle Plugin (2.x) + +A dependency on a specific IDE is defined in the Gradle build script using the builtin extensions listed in [](tools_intellij_platform_gradle_plugin_dependencies_extension.md#target-platforms). +Then, dependencies on required bundled modules and plugins must be defined in the plugin.xml file. +The necessary configuration for the corresponding product can be found under _Product Specific_ (for example, for [WebStorm](webstorm.md)). + +See also [](plugin_compatibility.md). + +## Gradle IntelliJ Plugin (1.x) +{id="gradle1"} To create a new Gradle plugin project, follow the tutorial on the [](creating_plugin_project.md) page. The tutorial produces a skeleton Gradle project suitable to use as a starting point. -Modifications are needed to the skeleton project's Gradle build script and [plugin.xml](plugin_configuration_file.md) files, as described below, and on the individual product pages in _Product Specific_. -The Gradle build script is modified to specify the target product, determining the APIs available during development. -The plugin.xml file is modified to declare the plugin's dependencies on modules or libraries. - -## Configuring Gradle Build Script to Target Products Other Than IntelliJ IDEA - The best practice is to use the [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property to specify the target product. For example, `PY` for PyCharm Professional. -Configuration using an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property is explained in the [](#configuring-plugin-projects-using-a-product-specific-attribute) section below. +Configuration using an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property is explained in the [](#using-a-product-specific-attribute) section below. NOTE: Not all products have an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property defined by the [](tools_gradle_intellij_plugin.md), for example, [Android Studio](android_studio.md) and [PhpStorm](phpstorm.md). Please see their respective pages for configuration and [](#configuring-gradle-build-script-using-the-intellij-idea-product-attribute) below. -> To target multiple products (e.g., IntelliJ IDEA and PyCharm) with the same plugin, see [](plugin_compatibility.md) page. +All the Gradle configuration attributes described here are discussed in-depth on the [](configuring_plugin_project.md) and the [](tools_gradle_intellij_plugin.md). + +> To target multiple products (for example, IntelliJ IDEA and PyCharm) with the same plugin, see [](plugin_compatibility.md) page. > {style="note"} -### Configuring Plugin Projects Using a Product-Specific Attribute +### Using a Product-Specific Attribute If the [](tools_gradle_intellij_plugin.md) supports a target product directly, there will be an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property defined. Specifying the target as a product-specific [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property has two advantages: + * The APIs available to the plugin will be limited to only what is defined in the target product (unless additional plugin dependencies are specified). * The default [](ide_development_instance.md) for running the plugin will be the target product. @@ -74,7 +78,7 @@ intellij { -### Configuring Plugin Projects Using the IntelliJ IDEA Product Attribute +### Using the IntelliJ IDEA Product Attribute If the [](tools_gradle_intellij_plugin.md) does not directly support an IntelliJ Platform-based product, the Gradle build script can still be configured to target the desired product. In this case, the build script is configured to use IntelliJ IDEA (Community or Ultimate Edition) as the basis for the available APIs. @@ -83,6 +87,7 @@ However, testing the plugin project in the target product itself helps to find s Additional configuration must be done to match the version of IntelliJ IDEA to the version of the target product. Understanding the relationship between build numbers is critical when using this approach to project configuration: + * _targetIDE_ is the (version-specific) IntelliJ Platform-based IDE in which the plugin is intended to run, such as Android Studio or PhpStorm. * _baseIntelliJPlatformVersion_ is the (version-specific) IntelliJ Platform used in the build of the _targetIDE_. The IntelliJ Platform is defined by a specific build of the IntelliJ IDEA Community Edition. @@ -109,6 +114,7 @@ Additional ways include hovering over the version number for a product in [Toolb In this example, IntelliJ IDEA Community Edition (which defines the IntelliJ Platform) for `2019.2.4` is build number `192.7142.36`. Although the *FIX* versions are different, this is not uncommon between products, and the builds are still compatible. The *BRANCH* and *BUILD* numbers match, therefore in this PhpStorm example: + * The _targetIDE_ is PhpStorm, build `192.7142.41`, * The _baseIntelliJPlatformVersion_ (IntelliJ IDEA Community Edition) is build `192.7142.36` @@ -184,7 +190,7 @@ runIde { -## Configuring plugin.xml +### Configuring plugin.xml As discussed on the [](plugin_compatibility.md#declaring-plugin-dependencies) page of this guide, a plugin's dependency on [](plugin_compatibility.md#modules-specific-to-functionality) must be declared in plugin.xml. When using features (APIs) specific to the target product, a dependency on the target product module must be declared, as shown in the code snippet below. diff --git a/topics/products/goland/goland.md b/topics/products/goland/goland.md index 73c716872..e09fcf180 100644 --- a/topics/products/goland/goland.md +++ b/topics/products/goland/goland.md @@ -50,7 +50,7 @@ dependencies { -The configuration of targeting GoLand IDE follows the methods described in [Configuring Plugin Projects Using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute). +The configuration of targeting GoLand IDE follows the methods described in [Configuring Plugin Projects Using a Product-Specific Attribute](dev_alternate_products.md#using-a-product-specific-attribute). Starting with 2020.2, it's possible to configure `GO` for `intellij.type` in the Gradle build script. If you need to use Go language APIs, specifying the `GO` platform type is not enough - it is required to add a dependency to the `org.jetbrains.plugins.go` plugin. @@ -88,7 +88,7 @@ intellij { -The configuration of GoLand plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). +The configuration of GoLand plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. diff --git a/topics/products/idea/idea.md b/topics/products/idea/idea.md index 3188461c1..b1ce27f13 100644 --- a/topics/products/idea/idea.md +++ b/topics/products/idea/idea.md @@ -45,7 +45,7 @@ dependencies { -The configuration of IntelliJ IDEA plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute). +The configuration of IntelliJ IDEA plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#using-the-intellij-idea-product-attribute). | `gradle-intellij-plugin` Attribute | Attribute Value | |----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| diff --git a/topics/products/phpstorm/phpstorm.md b/topics/products/phpstorm/phpstorm.md index 4711171c2..9ee925ffd 100644 --- a/topics/products/phpstorm/phpstorm.md +++ b/topics/products/phpstorm/phpstorm.md @@ -59,7 +59,7 @@ dependencies { -The configuration of targeting PhpStorm IDE follows the methods described in [Configuring Plugin Projects Using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute). +The configuration of targeting PhpStorm IDE follows the methods described in [Configuring Plugin Projects Using a Product-Specific Attribute](dev_alternate_products.md#using-a-product-specific-attribute). The possibility of configuring the `PS` IntelliJ Platform type was introduced in [](tools_gradle_intellij_plugin.md) 1.8.0. Only the versions of PhpStorm 2022.2 and newer are supported. @@ -81,7 +81,7 @@ The IntelliJ IDEA Ultimate Edition (with the PHP plugin) must be used for develo However, this IntelliJ IDEA Ultimate configuration runs the risk of accidentally using some APIs that are not available in PhpStorm. The recommended best practice is to use PhpStorm for testing. -Configuration of a Gradle-based PhpStorm plugin project is used as a tutorial in the section [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute). +Configuration of a Gradle-based PhpStorm plugin project is used as a tutorial in the section [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#using-the-intellij-idea-product-attribute). Many techniques are discussed, such as choosing a version of IntelliJ IDEA Ultimate given a targeted version of PhpStorm. The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. diff --git a/topics/products/pycharm/pycharm.md b/topics/products/pycharm/pycharm.md index 29dc24739..6487c4da3 100644 --- a/topics/products/pycharm/pycharm.md +++ b/topics/products/pycharm/pycharm.md @@ -47,7 +47,7 @@ dependencies { -The configuration of PyCharm plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). +The configuration of PyCharm plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. diff --git a/topics/products/webstorm/webstorm.md b/topics/products/webstorm/webstorm.md index 5099e60dd..a792fd77d 100644 --- a/topics/products/webstorm/webstorm.md +++ b/topics/products/webstorm/webstorm.md @@ -52,7 +52,7 @@ dependencies { -The configuration of WebStorm plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute) and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml) for PhpStorm. +The configuration of WebStorm plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#using-the-intellij-idea-product-attribute) and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml) for PhpStorm. The table below summarizes the [](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute.