hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 10:17:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

Incorporated Yann's feedback.

Browse Source
This commit is contained in:
JohnHake 2019-05-20 22:53:25 -07:00
parent f97dbe8e1f
commit f10e35f30f
6 changed files with 61 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
code_samples/action_basics/build.gradle
View File

@ -1,6 +1,6 @@
plugins {
id 'java'
id 'org.jetbrains.intellij' version '0.4.7'
id 'org.jetbrains.intellij' version '0.4.8'
}
sourceCompatibility = 1.8
@ -27,4 +27,4 @@ intellij {
}
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc
jar.dependsOn javadoc

13
code_samples/action_basics/src/main/java/org/intellij/sdk/action/DynamicActionGroup.java
View File

@ -2,7 +2,6 @@
package org.intellij.sdk.action;
import com.intellij.icons.AllIcons;
import com.intellij.openapi.actionSystem.ActionGroup;
import com.intellij.openapi.actionSystem.AnAction;
import com.intellij.openapi.actionSystem.AnActionEvent;
@ -24,16 +23,16 @@ public class DynamicActionGroup extends ActionGroup {
/**
* Returns an array of menu actions for the group.
*
* @param anActionEvent Event received when the associated group-id menu is chosen.
* @param e Event received when the associated group-id menu is chosen.
* @return AnAction[] An instance of AnAction, in this case containing a single instance of the
* PopDialogAction class.
* PopupDialogAction class.
*/
@NotNull
@Override
public AnAction[] getChildren(AnActionEvent anActionEvent) {
return new AnAction[]{ new PopDialogAction("Action Added at Runtime",
"Dynamic Action Demo",
ActionBasicsIcons.Sdk_default_icon)
public AnAction[] getChildren(AnActionEvent e) {
return new AnAction[]{ new PopupDialogAction("Action Added at Runtime",
"Dynamic Action Demo",
ActionBasicsIcons.Sdk_default_icon)
};
}

24
code_samples/action_basics/src/main/java/org/intellij/sdk/action/PopDialogAction.java → code_samples/action_basics/src/main/java/org/intellij/sdk/action/PopupDialogAction.java
View File

@ -19,15 +19,15 @@ import javax.swing.*;
* Typically this class is instantiated by the IntelliJ Platform framework based on declarations
* in the plugin.xml file. But when added at runtime this class is instantiated by an action group.
*/
public class PopDialogAction extends AnAction {
public class PopupDialogAction extends AnAction {
/**
* This default constructor is used by the IntelliJ Platform framework to
* instantiate this class based on plugin.xml declarations. Only needed in PopDialogAction
* instantiate this class based on plugin.xml declarations. Only needed in PopupDialogAction
* class because a second constructor is overridden.
* @see AnAction#AnAction()
*/
public PopDialogAction() {
public PopupDialogAction() {
super();
}
@ -35,12 +35,12 @@ public class PopDialogAction extends AnAction {
* This constructor is used to support dynamically added menu actions.
* It sets the text, description to be displayed for the menu item.
* Otherwise, the default AnAction constructor is used by the IntelliJ Platform.
* @param menuText The text to be displayed as a menu item.
* @param menuDescription The description of the menu item.
* @param menuIcon The icon to be used with the menu item.
* @param text The text to be displayed as a menu item.
* @param description The description of the menu item.
* @param icon The icon to be used with the menu item.
*/
public PopDialogAction(@Nullable String menuText, @Nullable String menuDescription, @Nullable Icon menuIcon) {
super(menuText, menuDescription, menuIcon);
public PopupDialogAction(@Nullable String text, @Nullable String description, @Nullable Icon icon) {
super(text, description, icon);
}
/**
@ -66,13 +66,13 @@ public class PopDialogAction extends AnAction {
/**
* Determines whether this menu item is available for the current context.
* Requires a project to be open.
* @param evnt Event received when the associated group-id menu is chosen.
* @param e Event received when the associated group-id menu is chosen.
*/
@Override
public void update(AnActionEvent evnt) {
public void update(AnActionEvent e) {
// Set the availability based on whether a project is open
Project project = evnt.getProject();
evnt.getPresentation().setEnabledAndVisible(project != null);
Project project = e.getProject();
e.getPresentation().setEnabledAndVisible(project != null);
}
}

10
code_samples/action_basics/src/main/resources/META-INF/plugin.xml
View File

@ -40,7 +40,7 @@
The optional "use-shortcut-of" attribute specifies the ID of the action whose keyboard shortcut this action will use.
The optional "description" attribute specifies the text which is displayed in the status bar when the action is focused.
The optional "icon" attribute specifies the icon which is displayed on the toolbar button or next to the menu item. -->
<action id="org.intellij.sdk.action.PopDialogAction" class="org.intellij.sdk.action.PopDialogAction"
<action id="org.intellij.sdk.action.PopupDialogAction" class="org.intellij.sdk.action.PopupDialogAction"
text="Pop Dialog Action" description="SDK Action Example" icon="ActionBasicsIcons.Sdk_default_icon">
<!-- The <keyboard-shortcut> node specifies the keyboard shortcut for the action. An action can have several keyboard shortcuts.
The mandatory "first-keystroke" attribute specifies the first keystroke of the action. The key strokes are specified according to the regular Swing rules.
@ -80,12 +80,12 @@
<!-- All off the following menu groups add the action SimplePopDialogAction to menus in different ways.
Note the action ids are unique. -->
<!-- GroupedActions demonstrates declaring an action group using the default ActionGroup implementation provided by the
IntelliJ Platform framework. (Note the lack of a "class" attribute.) GroupedActions gets inserted after PopDialogAction
IntelliJ Platform framework. (Note the lack of a "class" attribute.) GroupedActions gets inserted after PopupDialogAction
in the Tools menu. Because the group's implementation is default, it cannot impose enable/disable conditions. Instead it
must rely on the conditions imposed by the parent menu where it is inserted. It declares one action in the group. -->
<group id="org.intellij.sdk.action.GroupedActions" text="Static Grouped Actions" popup="true" icon="ActionBasicsIcons.Sdk_default_icon">
<add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.intellij.sdk.action.PopDialogAction"/>
<action class="org.intellij.sdk.action.PopDialogAction" id="org.intellij.sdk.action.GroupPopDialogAction"
<add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.intellij.sdk.action.PopupDialogAction"/>
<action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.GroupPopDialogAction"
text="A Group Action" description="SDK Static Grouped Action Example" icon="ActionBasicsIcons.Sdk_default_icon">
</action>
</group>
@ -94,7 +94,7 @@
<group id="org.intellij.sdk.action.CustomDefaultActionGroup" class="org.intellij.sdk.action.CustomDefaultActionGroup" popup="true"
text="Popup Grouped Actions" description="Custom DefaultActionGroup Demo" icon="ActionBasicsIcons.Sdk_default_icon">
<add-to-group group-id="EditorPopupMenu" anchor="first"/>
<action class="org.intellij.sdk.action.PopDialogAction" id="org.intellij.sdk.action.CustomGroupedAction"
<action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.CustomGroupedAction"
text="A Popup Action" description="SDK Popup Grouped Action Example" icon="ActionBasicsIcons.Sdk_default_icon"/>
</group>
<!-- DynamicActionGroup demonstrates declaring an action group without a static action declaration.

15
intro/intellij_platform.md
View File

@ -2,13 +2,13 @@
title: What is the IntelliJ Platform?
---
The _IntelliJ Platform_ is not a product in and of itself, but provides a platform for building IDEs. It is used to power JetBrains products such as [IntelliJ IDEA](https://www.jetbrains.com/idea/). It is also Open Source and can be used by third parties to build IDEs, such as [Android Studio](https://developer.android.com/studio/index.html) from Google.
The _IntelliJ Platform_ is not a product in and of itself but provides a platform for building IDEs. It is used to power JetBrains products such as [IntelliJ IDEA](https://www.jetbrains.com/idea/). It is also Open Source and can be used by third parties to build IDEs, such as [Android Studio](https://developer.android.com/studio/index.html) from Google.
The IntelliJ Platform provides all of the infrastructure that these IDEs need to provide rich language tooling support. It provides a component driven, cross-platform JVM based application host with a high-level user interface toolkit for creating tool windows, tree views and lists (supporting fast search) as well as popup menus and dialogs.
It also includes an image editor as well as a full text editor, and provides abstract implementations of syntax highlighting, code folding, code completion, and other rich text editing features.
Furthermore, it includes open APIs to build common IDE functionality, such as a project model and a build system. It also provides infrastructure for a very rich debugging experience, with language agnostic advanced breakpoint support, call stacks, watch windows and expression evaluation.
Furthermore, it includes open APIs to build common IDE functionality, such as a project model and a build system. It also provides infrastructure for a very rich debugging experience, with language agnostic advanced breakpoint support, call stacks, watch windows, and expression evaluation.
But the IntelliJ Platform's real power comes from the Program Structure Interface (PSI). This is a set of functionality that can be used to parse files and build rich syntactic and semantic models of the code, and to build indexes from this data. This powers a lot of functionality, from quick navigating to files, types and symbols, to the contents of code completion windows and find usages, code inspections and code rewriting, for quick fixes or refactorings, as well as many other features.
@ -21,7 +21,7 @@ Products built on the IntelliJ Platform are extensible applications, with the pl
Plugins can extend the platform in lots of ways, from adding a simple menu item to adding support for a complete language, build system and debugger. A lot of the existing functionality in the IntelliJ Platform is written as plugins that can be included or excluded depending on the needs of the end product. See the [Quick Start Guide](/basics.md) for more details.
The IntelliJ Platform is a JVM application, written mostly in Java and Kotlin. You should be familiar with these languages, and associated tooling, in order to write plugins for products based on the IntelliJ Platform. At this time, it's not possible to extend the IntelliJ Platform in non-JVM languages.
The IntelliJ Platform is a JVM application, written mostly in Java and Kotlin. You should be experienced with these languages, large libraries written in them, their associated tooling, and large open source projects to write plugins for products based on the IntelliJ Platform. At this time, it's not possible to extend the IntelliJ Platform in non-JVM languages.
## Open Source
@ -53,13 +53,10 @@ The following IDEs are based on the IntelliJ Platform:
* [RubyMine](https://www.jetbrains.com/ruby/)
* [WebStorm](https://www.jetbrains.com/webstorm/)
* [Android Studio](https://developer.android.com/studio/index.html) IDE from Google.
* [CUBA Studio](https://www.cuba-platform.com/)
JetBrains [Rider](https://www.jetbrains.com/rider/) uses the IntelliJ Platform differently than other IntelliJ based IDEs. It uses the IntelliJ Platform to provide the user interface for a C# and .NET IDE, with the standard IntelliJ editors, tool windows, debugging experience and so on. It also integrates into the standard Find Usages and Search Everywhere UI, and makes use of code completion, syntax highlighting and so on.
JetBrains [Rider](https://www.jetbrains.com/rider/) uses the IntelliJ Platform differently than other IntelliJ based IDEs. It uses the IntelliJ Platform to provide the user interface for a C# and .NET IDE, with the standard IntelliJ editors, tool windows, debugging experience and so on. It also integrates into the standard Find Usages and Search Everywhere UI, and makes use of code completion, syntax highlighting, and so on.
However, Rider doesn't create a full PSI (syntactic and semantic) model for C# files. Instead, it reuses [ReSharper](https://www.jetbrains.com/resharper/) to provide language functionality. All of the C# PSI model, and all inspections and code rewriting, such as quick fixes and refactorings are run out of process, in a command line version of ReSharper. This means that creating a plugin for Rider involves two parts - a plugin that lives in the IntelliJ "front end" to show user interface, and a plugin that lives in the ReSharper "back end" to analyze and work with the C# PSI.
However, Rider doesn't create a full PSI (syntactic and semantic) model for C# files. Instead, it reuses [ReSharper](https://www.jetbrains.com/resharper/) to provide language functionality. All of the C# PSI model and all inspections and code rewriting, such as quick fixes and refactorings are run out of process, in a command line version of ReSharper. This means that creating a plugin for Rider involves two parts - a plugin that lives in the IntelliJ "front end" to show user interface, and a plugin that lives in the ReSharper "back end" to analyze and work with the C# PSI.
Fortunately, many plugins can simply work with the ReSharper backend - Rider takes care of displaying the results of inspections and code completion, and many plugins can be written that don't require an IntelliJ UI component. More details can be found in the Product Specific section.
### Contributing
Of course, because the IntelliJ Platform is open source, we also accept [pull requests](https://github.com/JetBrains/intellij-community/pulls) to the platform itself, rather than just opening the source for view. Issue tracking is managed with [YouTrack (using the IDEA project)](https://youtrack.jetbrains.com/issues/IDEA), and if you wish to contribute to the platform, it is usually a good idea to open an issue describing the changes you wish to make before making the changes - this allows the team chance to give feedback and advice. More details can be found in the section on [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).

130
tutorials/build_system/gradle_guide.md
View File

@ -19,80 +19,14 @@ When getting started, there are several items to note on the README page:
* At the top of the page, the latest production version (e.g. `0.4.8`) of the IntelliJ IDEA Gradle plugin is listed.
* Also at the top is the minimum version of Gradle required to support the IntelliJ IDEA Gradle plugin.
* The table of extended Gradle [Tasks](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#tasks) has a succinct description for each task added by the plugin.
This page will focus on the configuration and use four of those tasks:
* The [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) - `intellij { ... }`.
* The [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl) - `runIde { ... }`
* The [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) - `patchPluginXml { ... }`
* The [Publishing DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#publishing-dsl) - `publishPlugin { ... }`
* Examples are always a helpful resource, and at the bottom of the page are links to [example](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#examples) open source IntelliJ Platform plugin projects based on Gradle.
* Almost every Gradle plugin attribute has a default value that will work to get started on a Gradle-based IntelliJ Platform plugin project.
The remainder of this section is a summary of the `build.gradle` [Configuration](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#configuration) tasks, and their DSL attributes.
### Setup DSL
The `intellij{}` task (_Setup DSL_) has the most attributes, and it may be helpful to think of them in terms of groups.
See the [Setup portion](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) of the reference page for more details about each attribute:
* Configuration for the plugin project build:
* Attributes that specify the version of the IntelliJ Platform to be used for building the plugin project:
* `version` and `type`,
* or `localPath`
* Attribute that specifies the plugin project's dependencies on JetBrains repository plugins.
* `plugins`
* Build output: project artifact name and instrumentation directive.
* `pluginName`
* `instrumentCode`
* Management of downloads to support building and running against IntelliJ Platform (IDE) versions:
* Control source code download for the IntelliJ Platform-based IDE
* `downloadSources`
* Where to store IDE downloads locally
* `independencyCachePath`
* Where to get IDE, plugins, and JetBrains JRE
* `intellijRepo`
* `pluginsRepo`
* `jreRepo`
* Control of PatchPluginXml substitution for `since-build` and `until-build` attribute values of `<idea-version>` in `plugin.xml`:
* `updateSinceUntilBuild`
* `sameSinceUntilBuild`
* Manage aspects of the [IDE Development Instance](/basics/ide_development_instance.md) for running and debugging the plugin project:
* `sandboxDirectory`
* `alternativeIdePath`
### Running DSL
The `runIde{}` task extends the Gradle JavaExec task for building an IntelliJ Platform plugin project.
See the [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl) section of the reference page for more details about each attribute.
The attributes fall into two groups:
* Manage the version of the JetBrains JRE and location of the IDE to use as the IDE Development Instance:
* `jbrVersion`
* `ideaDirectory`
* Modify the locations of the [sandbox subdirectories](/basics/ide_development_instance.md#development-instance-settings-caches-logs-and-plugins):
* `configDirectory`
* `pluginsDirectory`
* `systemDirectory`
### Patching DSL
The `patchPluginXml{}` task replaces a subset of element and attribute values in a plugin project's `plugin.xml` file(s).
See the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) section of the reference page for more details about each attribute.
The behavior of this task depends in part on the attributes in the [Setup DSL](#setup-dsl) task.
The attributes fall into two groups:
* Values to be substituted:
* `version`
* `sinceBuild`
* `untilBuild`
* `pluginDescription`
* `changeNotes`
* Control of which `plugin.xml` files to patch, and where to store them after they are patched:
* `pluginXmlFiles`
* `destinationDir`
### Publishing DSL
The `publishPlugin{}` task enables Gradle to upload a plugin to a repository, most commonly the [JetBrains Plugin Repository](https://plugins.jetbrains.com).
See the [guide section](#publishing-with-the-gradle-plugin) below for more information about using these attributes.
The attributes in this task can be considered to fall into two groups:
* Credential-related:
* `token`
* `username`
* `password`
* Details of the upload:
* `distributionFile`
* `host`
* `channels`
## Guide to Configuring Gradle Plugin Functionality
This section presents a guided tour of Gradle plugin attributes to achieve commonly desired functionality.
@ -104,34 +38,34 @@ If a correct version of the specified IntelliJ Platform is not available on the
IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.
#### IntelliJ Platform Version
Explicitly setting `intellij.version` and `intellij.type` instructs the Gradle plugin to use that configuration of the IntelliJ Platform to build the plugin project.
Explicitly setting the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) attributes `intellij.version` and `intellij.type` commands the Gradle plugin to use that configuration of the IntelliJ Platform to build the plugin project.
If a local installation of IntelliJ IDEA is the desired type and version of the IntelliJ Platform, use `intellij.localPath` to point to that installation.
If the `intellij.localPath` attribute is set, do not set the `intellij.version` and `intellij.type` attributes as this could result in undefined behavior.
The Gradle plugin will use the version and type installed at `intellij.localPath`.
#### Plugin Dependencies
IntelliJ Platform plugin projects may depend on either bundled or third-party plugins.
In that case, a project should build against a version of those plugins that match the IntelliJ Platform version used to build the plugin project.
The Gradle plugin will fetch any plugins in the list defined by `intellij.plugins`.
See the Gradle plugin [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) for information about specifying the plugin and version.
See the Gradle plugin [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) for information about specifying the plugin and version.
Note that this attribute describes an environment dependency so that the Gradle plugin can fetch the required artifacts.
The IntelliJ Platform plugin project is still required to declare these dependencies in its `plugin.xml` file.
Note that this attribute describes an [IDE Development Instance](/basics/ide_development_instance.md) environment dependency so that the Gradle plugin can fetch the required artifacts.
The IntelliJ Platform plugin project is still required to declare these dependencies in its [Plugin Configuration](/basics/plugin_structure/plugin_configuration_file.md) (`plugin.xml`) file.
### Configuring the Gradle Plugin for Running IntelliJ Platform Plugins
By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin.
Using the corresponding JetBrains Java runtime is also the default, so for this use case no further configuration is required.
Using the corresponding JetBrains Runtime is also the default, so for this use case no further configuration is required.
#### Running Against Alternate Versions of the IntelliJ Platform
However, the version of the IntelliJ Platform used for the IDE Development Instance can be different from that used to build the plugin project.
Two Gradle plugin attributes control the version used for the IDE Development Instance:
* Setting `intellij.alternativeIdePath` to the path of the locally installed IDE to use for running the plugin.
This attribute is used when running the plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform).
* Setting `runIde.ideaDirectory` to the path of the locally installed (different version) IntelliJ IDEA to use for running the plugin.
* Setting the [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#running-dsl) attribute `runIde.ideaDirectory` to the path of the locally installed (different version) IntelliJ IDEA to use for running the plugin.
#### Running Against Alternate Versions of the Java Runtime
Every version of the IntelliJ Platform has a corresponding version of the JetBrains Java runtime.
A different version of the runtime can be used by specifying the `runIde.jbrVersion` attribute, describing a version of the JetBrains Java runtime that should be used by the IDE Development Instance.
#### Running Against Alternate Versions of the JetBrains Runtime
Every version of the IntelliJ Platform has a corresponding version of the JetBrains Runtime.
A different version of the runtime can be used by specifying the `runIde.jbrVersion` attribute, describing a version of the JetBrains Runtime that should be used by the IDE Development Instance.
The Gradle plugin will fetch the JetBrains Runtime as needed.
### Managing Directories used by the Gradle Plugin
There are several attributes to control where the Gradle plugin places directories for downloads and for use by the IDE Development Instance.
@ -146,62 +80,58 @@ However, it can be controlled by setting the `intellij.ideaDependencyCachePath`
### Controlling Downloads by the Gradle Plugin
As mentioned in the section about [configuring the intellij platform](#configuring-the-intellij-platform-used-for-building-plugin-projects) used for building plugin projects, the Gradle plugin will fetch the version of the IntelliJ Platform specified by the default or by the `intellij` attributes.
Whether to download source code is controlled by the attribute `intellij.downloadSources`. If source code isn't needed, then this is one download (and indexing) step that can be saved.
Standardizing the versions of the Gradle plugin and Gradle system across projects will minimize the time spent downloading versions.
There are controls for managing the IntelliJ IDEA Gradle plugin version, and the version of Gradle itself.
The Gradle plugin version is defined in the `plugins {}` section of a project's `build.gradle` file.
The Gradle version is in defined in a project's `gradle-wrapper.properties`.
### Patching the Plugin.XML File
With the exception of the `since-build` and `until-build` attributes of the `<idea-version>` element, all of the substitution attributes in the Patching DSL will be patched into the corresponding element values in a plugin project's `plugin.xml` file.
### Patching the Plugin Configuration File
A plugin project's `plugin.xml` file has values replaced from the attributes of the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl).
With the exception of the `since-build` and `until-build` attributes of the `<idea-version>` element, all of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's `plugin.xml` file.
The `since-build` and `until-build` substitution can be inhibited by setting `intellij.updateSinceUntilBuild` to `false`.
Substitution of at least the default value for the other attributes cannot be inhibited.
A best practice to avoid confusion is to replace the elements in `plugin.xml` that will be patched by the Gradle plugin with a comment.
That way the values for these parameters do not appear two places in the source code.
That way the values for these parameters do not appear in two places in the source code.
The Gradle plugin will add the necessary elements as part of the patching process.
For those attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements.
As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](prerequisites.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin), `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard.
However, the IntelliJ IDEA Gradle plugin does not combine and substitute those values for the default `<id>` and `<name>` elements in the `plugin.xml` file.
There is no IntelliJ Platform-related reason the value of those XML elements must match the Gradle plugin values, but it is considered a best practice to avoid confusion.
Smaller projects with only one `plugin.xml` file will likely use the defaults for which file to patch and where to store the patched file.
Larger projects, with multiple modules and more than one `plugin.xml` file, will need to construct a collection of files to be patched and declare them in `patchPluginXml.pluginXmlFiles`.
As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](prerequisites.html#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard.
However, the IntelliJ IDEA Gradle plugin does not combine and substitute those Gradle properties for the default `<id>` and `<name>` elements in the `plugin.xml` file.
There is no IntelliJ Platform-related reason these Gradle properties must equal the corresponding `plugin.xml` `<id>` and `<name>` elements, but synchronizing them is considered a best practice to avoid confusion.
### Publishing with the Gradle Plugin
Please review the [Publishing Plugins with Gradle](deployment.md) page before using these attributes.
Please review the [Publishing Plugins with Gradle](deployment.md) page before using the [Publishing DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#publishing-dsl) attributes.
That documentation explains three different ways to use Gradle for plugin uploads without exposing account credentials.
## Common IntelliJ IDEA Gradle Plugin Configurations
Combinations of attributes in different Gradle plugin tasks are often needed to create the desired build or IDE Development Instance environment.
This section review some of the more common configurations.
This section reviews some of the more common configurations.
### Plugins Targeting IntelliJ IDEA
IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward Gradle plugin configuration.
* Determine the version of IntelliJ IDEA to target; this is the version of the IntelliJ Platform.
* Determine the version of [IntelliJ IDEA to use for building the plugin project](#configuring-the-intellij-platform-used-for-building-plugin-projects); this is the desired version of the IntelliJ Platform.
This can be EAP (default) or determined from the [build number ranges](/basics/getting_started/build_number_ranges.md).
* If a production version of IntelliJ IDEA is the desired target, set the `intellij` [version attributes](#intellij-platform-version) accordingly.
* Set the necessary [plugin dependencies](#plugin-dependencies), if any.
* If the plugin project should be run or debugged in an IDE Development Instance based on the same IntelliJ IDEA version, no attributes need to be set.
* If the plugin project should be run or debugged in an IDE Development Instance based on the same IntelliJ IDEA version, no further attributes need to be set for the IDE Development Instance.
This is the default behavior and is the most common use case.
* If the plugin project should be run or debugged in an IDE Development Instance based on a different IntelliJ IDEA version, set [the path](#running-against-alternate-versions-of-the-intellij-platform) to the desired version.
* If the plugin project should be run using a JetBrains Java runtime other than the default for the IDE Development Instance, specify the [JetBrains Java runtime version](#running-against-alternate-versions-of-the-java-runtime).
* If the plugin project should be run using a JetBrains Runtime other than the default for the IDE Development Instance, specify the [JetBrains Runtime version](#running-against-alternate-versions-of-the-jetbrains-runtime).
* Set the appropriate attributes for [patching the `plugin.xml` file](#patching-the-plugin-configuration-file).
### Plugins Targeting Other IntelliJ Platform-Based IDEs
The Gradle plugin can also be configured for developing plugins to run in IDEs that are based on the IntelliJ Platform but are not IntelliJ IDEA.
This section uses the example of developing a plugin for PhpStorm.
It will be helpful to review the [PhpStorm Plugin Development](/products/phpstorm/phpstorm.md) section.
* The Gradle plugin attributes describing the configuration of the IntelliJ Platform used to build the plugin project must be explicitly set.
* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](#configuring-the-intellij-platform-used-for-building-plugin-projects) must be explicitly set.
The type will be "IC" because the IntelliJ Platform is defined by the IntelliJ IDEA Community Edition.
The BRANCH.BUILD number of the IntelliJ Platform (IntelliJ IDEA CE) is the same as for the PhpStorm target.
Although the FIX (tertiary) number may differ between the same versions of the applications, it won't affect the match of the IntelliJ Platform.
* All PhpStorm plugin projects have a dependency on the PhpStorm OpenAPI Library.
Any plugin targeting PhpStorm must list a dependency on the PHP plugin, and its version must be compatible with the target version of PhpStorm.
The plugin dependency must be declared using the Gradle plugin `intellij.plugins` attribute, which lists the FQN and version of the plugin dependency.
The plugin dependency must be declared using the Gradle plugin `intellij.plugins` attribute, which lists the `id` and `version` of the plugin dependency.
* The best practice is to use the target version of PhpStorm as the IDE Development Instance.
That enables running and debugging the plugin in the target (e.g., PhpStorm) application.
The choice of application to use for the IDE Development Instance is configured using the Gradle plugin attribute `intellij.alternativeIdePath`.