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

Complete guide page

Browse Source
This commit is contained in:
JohnHake 2019-04-23 16:38:46 -07:00
parent 7288bbff04
commit d566de69be
7 changed files with 278 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -37,6 +37,7 @@ _includes
### Gradle template
.gradle
build/
_idea-sandbox/
# Ignore Gradle GUI config
gradle-app.setting

2
.idea/intellij-sdk-docs.iml generated
View File

@ -5,7 +5,7 @@
<excludeFolder url="file://$MODULE_DIR$/.bundle" />
<excludeFolder url="file://$MODULE_DIR$/.git-metadata" />
<excludeFolder url="file://$MODULE_DIR$/_site" />
<excludeFolder url="file://$MODULE_DIR$/code_samples/Build" />
<excludeFolder url="file://$MODULE_DIR$/code_samples/_idea-sandbox" />
</content>
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />

1
_SUMMARY.md
View File

@ -16,6 +16,7 @@
* [Getting Started](basics/getting_started.md)
* [Using Gradle](tutorials/build_system.md)
* [Getting Started with Gradle](tutorials/build_system/prerequisites.md)
* [Configuring Gradle Projects](tutorials/build_system/gradle_guide.md)
* [Publishing Your Plugin](tutorials/build_system/deployment.md)
* [Using DevKit](basics/getting_started/using_dev_kit.md)
* [Setting Up a Development Environment](basics/getting_started/setting_up_environment.md)

25
code_samples/action_basics/build.gradle
View File

@ -3,7 +3,6 @@ plugins {
id 'org.jetbrains.intellij' version '0.4.7'
}
project.version '2.0.0'
sourceCompatibility = 1.8
repositories {
@ -16,22 +15,16 @@ dependencies {
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
// Define IntelliJ Platform API version to use for building this plugin
version '2019.1'
// Define a communal sandbox directory for running code sample plugins within an IDE.
sandboxDirectory = file("${project.projectDir}/../Build/idea-sandbox")
// Prevents patching <idea-version> attributes in plugin.xml
updateSinceUntilBuild = false
// Define a shared sandbox directory for running code sample plugins within an IDE.
sandboxDirectory = file("${project.projectDir}/../_idea-sandbox")
}
patchPluginXml {
version = project.version // <version> tag value
// Fix limited until-build default value.
sinceBuild = '191' // <idea-version> tag since-build attribute
untilBuild = '201.*' // <idea-version> tag until-build attribute - until v2020.1
}
// Define javadoc paths, force rebuild before jar is built
javadoc {
// Include all class files, e.g. from libraries
classpath = sourceSets.main.compileClasspath
}
jar.dependsOn javadoc
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc

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

@ -8,11 +8,10 @@
<name>SDK Action Sample Project</name>
<!-- The version of this plugin -->
<!-- <version>Replaced by patchPluginXml.version in build.gradle</version>-->
<version>2.0.0</version>
<!-- Compatible with the following versions of IntelliJ Platform -->
<!-- The <idea-version> attributes are updated by intellij.updateSinceUntilBuild,
patchPluginXml.sinceBuild and patchPlugin.untilBuild in build.gradle -->
<idea-version since-build="183" until-build=""/>
<!-- Text to display as description on Preferences/Settings | Plugin page -->
<description>
@ -31,7 +30,7 @@
</change-notes>
<!-- Text to display as company information on Preferences/Settings | Plugin page -->
<vendor email="faux-email@jetbrains.com" url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
<vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
<actions>
<!-- The <action> element defines an action to register.

56
intro/intellij_platform.md
View File

@ -2,44 +2,64 @@
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/), [WebStorm](https://www.jetbrains.com/webstorm/), [RubyMine](https://www.jetbrains.com/ruby/), [DataGrip](https://www.jetbrains.com/datagrip/) and [Rider](https://www.jetbrains.com/rider/). 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.
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 pluggable 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.
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.
The IntelliJ Platform includes parsers and a PSI model for a number of languages, and its extensible nature means that it is possible to add support for other languages.
The _IntelliJ Platform_ includes parsers and a PSI model for a number of languages, and its composable nature means that it is possible to add support for other languages.
## Plugins
Products built on the _IntelliJ Platform_ are composable applications, with the platform being responsible for the creation of components, and the injection of dependencies into classes. The _IntelliJ Platform_ fully supports plugins, and JetBrains hosts a [plugin repository](https://plugins.jetbrains.com) that can be used to distribute plugins that support one or more of the products. It is also possible to host your own repositories, and distribute plugins separately.
Products built on the IntelliJ Platform are extensible applications, with the platform being responsible for the creation of components, and the injection of dependencies into classes. The IntelliJ Platform fully supports plugins, and JetBrains hosts a [plugin repository](https://plugins.jetbrains.com) that can be used to distribute plugins that support one or more of the products. It is also possible to host your own repositories, and distribute plugins separately.
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 section on [Plugins](/basics.md) for more details.
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 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.
## Open Source
The _IntelliJ Platform_ is Open Source, under the [Apache license](upsource:///LICENSE.txt), and [hosted on GitHub](https://github.com/JetBrains/intellij-community).
The IntelliJ Platform is Open Source, under the [Apache license](upsource:///LICENSE.txt), and [hosted on GitHub](https://github.com/JetBrains/intellij-community).
While this guide refers to the _IntelliJ Platform_ as a separate entity, there is no "IntelliJ Platform" GitHub repo. Instead, the platform is considered to be an almost complete overlap with the IntelliJ IDEA Community Edition, which is a free and Open Source version of IntelliJ IDEA Ultimate (the GitHub repo linked above is the [JetBrains/intellij-community](https://github.com/JetBrains/intellij-community) repo).
While this guide refers to the IntelliJ Platform as a separate entity, there is no "IntelliJ Platform" GitHub repo. Instead, the platform is considered to be an almost complete overlap with the IntelliJ IDEA Community Edition, which is a free and Open Source version of IntelliJ IDEA Ultimate (the GitHub repo linked above is the [JetBrains/intellij-community](https://github.com/JetBrains/intellij-community) repo).
IntelliJ IDEA Ultimate is a superset of the IntelliJ IDEA Community Edition. It is based on the community edition, but includes closed source plugins ([see this feature comparison](https://www.jetbrains.com/idea/features/editions_comparison_matrix.html)). Similarly, other products such as WebStorm and DataGrip are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins.
The version of the IntelliJ Platform is defined by the version of the corresponding release of IntelliJ IDEA Community Edition.
For example, to build a plugin against IntelliJ IDEA (v2019.1.1,) build #191.6707.61, means specifying the same build number tag to get the correct Intellij Platform files from the `intellij-community` repo.
See the [build number ranges](/basics/getting_started/build_number_ranges.md) page for more information about build numbers corresponding to version numbering.
This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repo. This is what we call the _IntelliJ Platform_.
Typically, an IDE that is based on the IntelliJ Platform will include the `intellij-community` repo as a Git submodule and provide configuration to describe which plugins from the `intellij-community`, and which custom plugins will make up the product. This is how the IDEA Ultimate team work, and they contribute code to both the custom plugins and the IntelliJ Platform itself.
Typically, an IDE that is based on the _IntelliJ Platform_ will include the `intellij-community` repo as a Git submodule and provide configuration to describe which plugins from the `intellij-community`, and which custom plugins will make up the product. This is how the IDEA Ultimate team work, and they contribute code to both the custom plugins and the _IntelliJ Platform_ itself.
### IDEs Based on the IntelliJ Platform
The IntelliJ Platform underlies many JetBrains IDEs.
IntelliJ IDEA Ultimate is a superset of the IntelliJ IDEA Community Edition, but includes closed source plugins ([see this feature comparison](https://www.jetbrains.com/idea/features/editions_comparison_matrix.html)). Similarly, other products such as WebStorm and DataGrip are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins.
This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repo.
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).
The following IDEs are based on the IntelliJ Platform:
* JetBrains IDEs
* [AppCode](https://www.jetbrains.com/objc/)
* [CLion](https://www.jetbrains.com/clion/)
* [DataGrip](https://www.jetbrains.com/datagrip/)
* [GoLand](https://www.jetbrains.com/go/)
* [IntelliJ IDEA](https://www.jetbrains.com/idea/)
* [MPS](https://www.jetbrains.com/mps/)
* [PhpStorm](https://www.jetbrains.com/phpstorm/)
* [PyCharm](https://www.jetbrains.com/pycharm/)
* [RubyMine](https://www.jetbrains.com/ruby/)
* [WebStorm](https://www.jetbrains.com/webstorm/)
* [Android Studio](https://developer.android.com/studio/index.html) IDE from Google.
## Rider
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.
[Rider](https://www.jetbrains.com/rider/) uses the _IntelliJ Platform_ differently to 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, toolwindows, 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, it 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 analyse 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).

225
tutorials/build_system/gradle_guide.md Normal file
View File

@ -0,0 +1,225 @@
---
title: Configuring Gradle for IntelliJ Platform Plugins
---
This page serves as a guide to Gradle-based plugin configuration for _IntelliJ Platform_ projects.
The IntelliJ IDEA Ultimate and Community editions bundle the Gradle and Plugin DevKit plugins to support Gradle-based development.
The [Getting Started with Gradle](prerequisites.md) page provides a tutorial for creating Gradle-based IntelliJ Platform plugins.
It may be useful to review the IntelliJ Platform page, particularly the description of versioning in the [Open Source](/intro/intellij_platform.md#open-source) section.
* bullet list
{:toc}
## Overview of the IntelliJ IDEA Gradle Plugin
The IntelliJ IDEA Gradle plugin is built from the open-source project `gradle-intellij-plugin`.
The plugin adds Gradle tasks for the `build.gradle` file that enable developing IntelliJ Platform plugins.
The [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) file for the `gradle-intellij-plugin` project is the reference for configuring these tasks.
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.
* 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.
### Configuring the IntelliJ Platform Used for Building Plugin Projects
By default, the Gradle plugin will build the plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.
If a correct version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type.
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.
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.
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.
### 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.
#### 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.
#### 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.
### 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.
The location of the [sandbox home](/basics/ide_development_instance.md#sandbox-home-location-for-gradle-based-plugin-projects) directory and its subdirectories can be controlled with Gradle plugin attributes.
The `intellij.sandboxDirectory` attribute is used to set the path for the sandbox directory to be used while running the plugin in an IDE Development Instance.
Locations of the sandbox [subdirectories](/basics/ide_development_instance.html#development-instance-settings-caches-logs-and-plugins) can be controlled using the `runIde.configDirectory`, `runIde.pluginsDirectory`, and `runIde.systemDirectory` attributes.
If the `intellij.sandboxDirectory` path is explicitly set, the subdirectory attributes default to the new sandbox directory.
The storage location of downloaded IDE versions and components defaults to the Gradle cache directory.
However, it can be controlled by setting the `intellij.ideaDependencyCachePath` attribute.
### 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.
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.
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`.
### Publishing with the Gradle Plugin
Please review the [Publishing Plugins with Gradle](deployment.md) page before using these 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.
### 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.
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.
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).
### 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 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 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`.
The snippet below is an example of configuring the Setup DSL in a `build.gradle` file to develop a plugin targeted at PhpStorm.
The configuration uses IntelliJ IDEA Community Edition v2019.1.2 (build 191.7141.44) as the IntelliJ Platform against which the plugin project is built.
It uses PhpStorm v2019.1.2 (build 191.7141.52) as the IDE Development Instance in which the plugin project is run and debugged.
```groovy
intellij {
// Define IntelliJ Platform against which to build the plugin project.
version '191.7141.44' // Same version (2019.1.2) as target PhpStorm
type 'IC' // Use IntelliJ IDEA CE as basis of IntelliJ Platform
// Require the Php plugin, must be compatible with target v2019.1.2
plugins 'com.jetbrains.php:191.6707.66'
// Path to installed v2019.1.2 PhpStorm to use as IDE Development Instance
alternativeIdePath '/Applications/apps/PhpStorm/ch-0/191.7141.52/PhpStorm.app/Contents'
}
```