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

Add comments from review.

Browse Source
This commit is contained in:
JohnHake 2019-06-15 20:29:24 -07:00
parent 9e3a64a75e
commit a80c00bd32
10 changed files with 383 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.idea/gradle.xml generated
View File

@ -3,17 +3,15 @@
<component name="GradleSettings">
<option name="linkedExternalProjectsSettings">
<GradleProjectSettings>
<option name="disableWrapperSourceDistributionNotification" value="true" />
<option name="distributionType" value="DEFAULT_WRAPPED" />
<option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/action_basics" />
<option name="gradleHome" value="C:/Program Files (x86)/Gradle/gradle-2.9" />
<option name="gradleJvm" value="1.8" />
<option name="gradleJvm" value="1.8 202b1483.58" />
<option name="modules">
<set>
<option value="$PROJECT_DIR$/code_samples/action_basics" />
</set>
</option>
<option name="useQualifiedModuleNames" value="true" />
</GradleProjectSettings>
<GradleProjectSettings>
<option name="distributionType" value="DEFAULT_WRAPPED" />

2
.idea/misc.xml generated
View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ExternalStorageConfigurationManager" enabled="true" />
<component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IC-191.6183.87" project-jdk-type="IDEA JDK">
<component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IU-191.7479.19" project-jdk-type="IDEA JDK">
<output url="file://$PROJECT_DIR$/Build" />
</component>
</project>

11
code_samples/action_basics/.gitignore vendored Normal file
View File

@ -0,0 +1,11 @@
# Created by .ignore support plugin (hsz.mobi)
### Gradle template
.gradle
build/
# Ignore Gradle GUI config
gradle-app.setting
# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
!gradle-wrapper.jar

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

@ -5,7 +5,7 @@
<id>org.intellij.sdk.action</id>
<!-- Text to display as name on Preferences/Settings | Plugin page -->
<name>SDK Action Sample Project</name>
<name>SDK: Action Sample Project</name>
<!-- The version of this plugin -->
<version>2.0.0</version>

4
code_samples/gradle_plugin_demo/build.gradle
View File

@ -1,3 +1,7 @@
plugins {
id "org.jetbrains.intellij" version "0.4.7"
}
sourceCompatibility = 1.8

164
intro/sdk_code_guidelines.md Normal file
View File

@ -0,0 +1,164 @@
---
title: Guidelines for Creating IntelliJ Platform SDK Code Samples
---
This document describes the coding guidelines used for authoring open source IntelliJ Platform SDK code samples.
Before you begin, please read this page thoroughly as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents.
For information about contributing to the IntelliJ Platform itself visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
* Dummy list item
{:toc}
## Objectives
Keep the following considerations in mind while authoring an SDK code sample:
* The purpose of an SDK sample is to demonstrate an implementation pattern to build on top of subsystems and components of the IntelliJ Platform.
* SDK code samples are instructional code, intended to teach.
* Instructional code differs from production code in some key aspects:
* Sacrifice some robustness in the interest of simplicity and brevity.
Use error checking where it is necessary to make a point about an implementation pitfall.
* Keep implementations as simple as possible, but use the full features of the IntelliJ Platform, Java language, and libraries.
* Use meaningful names for interfaces, classes, fields, methods, and extension points.
* Write instructional JavaDoc comments.
* Code samples replace lots of documentation.
* Aim for two levels of SDK samples:
* A _basic_ sample is focused on a particular subject by demonstrating a limited area of the IntelliJ Platform.
It should show all the components and architecture but ultimately accomplish something elementary.
For example, demonstrate persistence by storing only a `String`.
* An _advanced_ sample demonstrates how different parts of the IntelliJ Platform integrate and work together.
For example, combining inspections or intentions with non-trivial PsiTree manipulation.
Ultimately, the goal is to provide developers with roadmaps for implementing functionality in an IntelliJ Platform-based plugin.
Each roadmap should contain:
* Pointers to SDK documentation about the IntelliJ Platform APIs needed to implement the functionality.
* Pointers to relevant _basic_ SDK sample plugins.
* Pointers to related _advanced_ SDK sample plugins.
## Naming Conventions for SDK Plugins
For _basic_ samples, the naming convention is focused on the IntelliJ Platform APIs being demonstrated.
For example, `foo_basics` where `foo` corresponds to an IntelliJ Platform feature, framework, or component.
Some naming examples include `facet_basics` and `editor_basics`.
There is only one _basic_ sample per IntelliJ Platform API area.
For _advanced_ code samples, the name should reflect the complex functionality delivered by the plugin rather than the IntelliJ Platform APIs.
Advanced samples will be cross-referenced to the IntelliJ Platform APIs demonstrated in the sample.
Note that the naming convention relates to the `Artifact ID`, which is the Gradle property `rootProject.name`.
This is different than the `<name>` definition provided in the [`plugin.xml`](#pluginxml-conventions) file.
See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for more information about the distinction.
## Plugin Copyright Statements
Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:
```text
Copyright 2000-$today.year JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file."
```
The copyright statement must appear in every source file with the `$today.year` [Velocity](https://www.jetbrains.com/help/idea/copyright-profiles.html) template resolved.
## Plugin ID Conventions
The `Group ID` for SDK plugins is always `org.intellij.sdk`.
In general, the plugin ID is the `Group ID` concatenated with the `Artifact ID`.
For _basic_ code samples, it is not necessary to include "basic" in the plugin ID.
A plugin like `facet_basics` has the plugin ID `org.intellij.sdk.facet`.
## Plugin Package Names
Packages in plugins should begin with the plugin ID.
If there is only one package in a plugin, then the package name is the same as the plugin ID.
## Plugin Directory Structure
SDK sample code should have a standard directory footprint.
Standardized structure not only makes the samples simpler to navigate and understand, but it builds on the default Gradle plugin project structure.
The following is the directory structure for a `foo_basics` plugin.
```text
code_samples/
foo_basics/
gradle/
src/
main/
java/
icons/
FooBasicsIcons.java
resources/
icons/
sdk.svg # The standard SDK icon for menus, etc.
META-INF/
plugin.xml # The plugin configuration file
pluginIcon.svg # The standard SDK plugin icon
test/ # Omit if there are no tests
java/
resources/
build.gradle
gradlew
gradle.bat
settings.gradle
```
## build.gradle Conventions
New SDK code samples should be developed [using Gradle](/tutorials/build_system.md).
As of this writing, the use of Gradle in SDK code samples still relies heavily on the `plugin.xml` for specifying the plugin configuration.
At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration.
The default contents of a `build.gradle` file are produced by the [New Project Wizard](/tutorials/build_system/prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard).
A consistent structure for an SDK code sample's `build.gradle` file is important for clarity and is based on the default produced by the project wizard.
Comments in SDK code sample `build.gradle` files should only draw attention to the parts of the Gradle configuration that are unique for a plugin.
For SDK code samples, a few alterations are needed to the default build.gradle file produced by the plugin wizard:
* Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`).
See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in `plugin.xml`.
* Add the following statements to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section:
```groovy
// 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")
```
* Remove the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) (`patchPluginXml{}`) section.
It is not needed in SDK samples.
* Add the `javadoc` task to build documentation for the code sample:
```groovy
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc
```
## plugin.xml Conventions
A consistent structure for the [`plugin.xml`](/basics/plugin_structure/plugin_configuration_file.md) configuration file of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin.
Inconsistent element order is visually noisy.
Comment profusely about unique elements and configurations, and comment sparingly for the rest.
The sequence of elements in an SDK code sample `plugin.xml` file is:
* `<id>` Use the fully qualified [Plugin ID](#plugin-id-conventions).
* `<name>` The name value does not have to match the [Plugin Name](#naming-conventions-for-sdk-plugins).
It might reflect the functionality of the plugin.
The name must start with "SDK: ".
* `<version>` The code sample's version in MAJOR.MINOR.FIX format.
* MAJOR corresponds to a significant upgrade in functionality.
* MINOR corresponds to minor refactoring and small improvements in functionality.
* FIX corresponds to changes that fix problems without significant refactoring.
* `<idea-version/>` Set the attributes:
* `since-build` attribute to the earliest compatible build number of the IntelliJ Platform.
The default for SDK samples is "173".
* `until-build` Omit this attribute for new sample plugins.
SDK code samples are reviewed before every major release (20XX.1) to ensure compatibility with the latest IntelliJ Platform.
Add this attribute if a plugin sample is deprecated with a release of the IntelliJ Platform.
* `<depends>` Include at least one dependency with the module `com.intellij.modules.platform` to indicate basic plugin compatibility with IntelliJ Platform-based products.
Add `<depends>` elements containing module FQNs as needed to describe more specialized [Compatibility with Multiple Products](/basics/getting_started/plugin_compatibility.md), and any other [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md).
* `<description>` is a concise explanation of what is being demonstrated and how a user would access the functionality.
* `<change-notes>` is an ordered list by version numbers with a brief description of changes for each version.
* `<vendor>` Set the value to `IntelliJ Platform SDK`.
Set the attributes:
* `email` omit this attribute.
* `url` to the JetBrains plugin repository `"https://plugins.jetbrains.com"`
* The remainder of the [plugin configuration elements](/basics/plugin_structure/plugin_configuration_file.md) should only appear if they are needed by a specific plugin.
## Testing
IntelliJ Platform SDK code samples should be built and tested against the `since-build` version.
Code samples should build cleanly, with no warnings or errors, and new code samples should pass all default IntelliJ IDEA code inspections.
Testers should complete the following checklist.
Here the term "IDE" means the IntelliJ Platform-based IDE in which the plugin is designed to run:
* The plugin should load in the IDE.
* The correct information about the plugin should display in the **Preferences \| Plugins** panel.
* If applicable, the plugin UI such as tool windows, menu additions, etc. should display correctly.
* The functionality of the plugin should be tested with a sample file.
* If applicable, the plugin should pass unit tests.

14
tutorials/build_system.md
View File

@ -4,13 +4,19 @@ title: Building plugins with Gradle
The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended
solution for building IntelliJ plugins. The plugin takes care of the dependencies of your plugin project - both the
base IDE and the other plugins that your plugin may depend on.
base IDE and other plugin dependencies.
It also provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains plugins repository](/plugin_repository/index.md). To make sure that your plugin is not affected by [API changes](/reference_guide/api_changes_list.md)
which may happen between major releases of the platform, you can easily build your plugin against many versions
of the base IDE.
The following tutorial refers to materials that can be found in the included [gradle_plugin_demo](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/gradle_plugin_demo) project. Below are a series of guides to configuring Gradle support.
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
* [1. Getting Started](build_system/prerequisites.md)
* [2. Deploying a plugin](build_system/deployment.md)
> **Note** Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`.
Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases).
The following tutorial refers to materials that can be found in the included [gradle_plugin_demo](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/gradle_plugin_demo) project.
Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins:
* [1. Getting Started with Gradle-Based Plugins](build_system/prerequisites.md)
* [2. Configuring Gradle-Based Plugins](build_system/gradle_guide.md)
* [3. Deploying a Plugin with Gradle](build_system/deployment.md)

2
tutorials/build_system/deployment.md
View File

@ -5,6 +5,8 @@ title: Publishing Plugins with Gradle
Once you have configured Gradle support, you can automatically build and deploy your plugin to the [JetBrains Plugin Repository](https://plugins.jetbrains.com). To do so, you
will need to have already published the plugin to the plugin repository. For detailed information, please see the guide to [publishing a plugin](../../basics/getting_started/publishing_plugin.md).
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
### 2.0 Add your account credentials
In order to deploy a plugin to the plugin repository, you will first need to supply your JetBrains Account credentials.

34
tutorials/build_system/gradle_guide.md
View File

@ -57,11 +57,8 @@ Using the corresponding JetBrains Runtime is also the default, so for this use c
#### Running Against Alternate Versions and Types of IntelliJ Platform-Based IDEs
The IntelliJ Platform IDE used for the Development Instance can be different from that used to build the plugin project.
Two Gradle plugin attributes can be set to the path of an alternate (different version or non-IDEA) IntelliJ Platform-based IDE to control the configuration used for the IDE Development Instance:
* Setting the [Running DSL](https://github.com/jetbrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideaDirectory` will define an IDE to be used for the Development Instance in that single `runIde` task.
* Setting the Setup DSL attribute `intellij.alternativeIdePath` will define an IDE as the default value for all `runIdea.ideaDirectory` attributes of all `runIde` tasks, including `runIde.buildSearchableOptions`.
It also sets the default IDE configuration for running tests and retrieving versions of JetBrains Runtimes.
This attribute is commonly used when running the plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform).
Setting the [Running DSL](https://github.com/jetbrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideaDirectory` will define an IDE to be used for the Development Instance in that single `runIde` task.
This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform).
#### Running Against Alternate Versions of the JetBrains Runtime
Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](/basics/ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).
@ -87,19 +84,22 @@ The Gradle plugin version is defined in the `plugins {}` section of a project's
The Gradle version is in defined in a project's `gradle-wrapper.properties`.
### 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#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 plugin project's `plugin.xml` file has element values that are "patched" at build time from the attributes of the `patchPluginXml` ([Patching DSL](https://github.com/jetbrains/gradle-intellij-plugin#patching-dsl)) task.
As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's `plugin.xml` file:
* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in plugin.xml _regardless of whether the `patchPluginXml` task appears in the `build.gradle` file_.
* For example, the default values for the attributes `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are defined based on the declared (or default) value of `intellij.version`.
So by default `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are substituted into the `<idea-version>` element's `since-build` and `until-build` attributes in the `plugin.xml` file.
* If a `patchPluginXml` attribute value is explicitly defined, the attribute value will be substituted in `plugin.xml`.
* If both `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` attributes are explicitly set, both are substituted in `plugin.xml`.
* If one attribute is explicitly set (e.g. `patchPluginXml.sinceBuild`) and one is not (e.g. `patchPluginXml.untilBuild` has default value,) both attributes are patched at their respective (explicit and default) values.
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 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.
For those `patchPluginXml` 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.md#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 the [Publishing DSL](https://github.com/jetbrains/gradle-intellij-plugin#publishing-dsl) attributes.
@ -138,7 +138,7 @@ It will be helpful to review the [PhpStorm Plugin Development](/products/phpstor
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 snippet below is an example of configuring the Setup and Running DSLs 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
@ -148,10 +148,10 @@ It uses PhpStorm v2019.1.2 (build 191.7141.52) as the IDE Development Instance i
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'
}
runIde {
// Path to installed v2019.1.2 PhpStorm to use as IDE Development Instance
ideaDirectory '/Applications/apps/PhpStorm/ch-0/191.7141.52/PhpStorm.app/Contents'
}
```

247
tutorials/build_system/prerequisites.md
View File

@ -2,116 +2,201 @@
title: Getting Started with Gradle
---
Adding Gradle build support to an IntelliJ Platform Plugin requires a recent distribution of the Gradle build system and IntelliJ IDEA (Community or Ultimate).
Gradle is the preferred solution for creating IntelliJ Platform plugins.
The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based development.
These IntelliJ IDEA plugins are _Gradle_ and _Plugin DevKit_, which are enabled by default.
To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html).
### 1.0 Download and Install IntelliJ IDEA
* bullet list
{:toc}
Download and install either IntelliJ IDEA Ultimate or the IntelliJ IDEA Community Edition.
### 1.1 Ensure that 'Gradle' and 'Plugin DevKit' Plugins are Enabled
> **WARNING** When adding additional repositories to your Gradle build script, make sure to use HTTPS always.
You can verify that the plugins are enabled by visiting **Settings \| Plugins**.
## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard
IntelliJ IDEA supports creating new Gradle-based IntelliJ Platform plugin projects using the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle).
The Wizard creates all the necessary project files based on a few template inputs.
![Ensure the Gradle plugin is enabled](img/step0_gradle_enabled.png){:width="858px"}
Before creating a new Gradle project, familiarize yourself with the IntelliJ IDEA help topic [Creating a new Gradle project](https://www.jetbrains.com/help/idea/getting-started-with-gradle.html#create_gradle_project), which is a tutorial for creating general Gradle projects in IntelliJ IDEA.
This page emphasizes the steps in the process for creating IntelliJ Platform plugin projects that are Gradle-based.
### 1.2 Create a Plugin Project from Scratch
Launch the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle).
It guides you through the Gradle project creation process with four screens.
IntelliJ IDEA supports automatically creating new plugin projects using Gradle, with all the necessary `build.gradle`
setup performed automatically. This can also be used to convert an existing plugin to Gradle, if Gradle is not able to
convert the existing project - in this case, you need to copy over the sources to the new project.
To do so, create a new project in IntelliJ IDEA by opening **File \| New... \| Project**, and select Gradle from the dialog box.
In the "Additional Libraries and Frameworks" page, check "IntelliJ Platform Plugin".
### New Project Configuration Screen
On the first screen, the type of project is configured:
* From the _product category_ pane on the left, choose _Gradle_.
* Specify the _Project SDK_ based on the Java 8 JDK.
This SDK will be the default JRE used to run Gradle, and the JDK version used to compile the plugin Java source.
Based on the Project SDK, the IntelliJ IDEA Gradle Plugin will download the corresponding version of the IntelliJ Platform-based IDE automatically.
* In the _Additional Libraries and Frameworks_ panel, select _Java_ and _IntelliJ Platform Plugin_, then click _Next_.
![Select the Gradle facet in the Project Creation Wizard](img/step1_new_gradle_project.png){:width="800px"}
The Project Creation Wizard will now guide you through the Gradle project creation process. You will need to specify a Group ID, Artifact ID, and Version:
### Project Naming Screen
On this, the second screen of the Wizard, specify a [Group ID, Artifact ID, and plugin Version](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle) using [Maven naming](https://maven.apache.org/guides/mini/guide-naming-conventions.html) conventions.
* _Group ID_ is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's `build.gradle` file.
For this example, enter "com.your.company".
* _Artifact ID_ is the default name of the project JAR file (without version).
It is also used for the Gradle property `rootProject.name` value in the project's `settings.gradle` file.
For this example, enter "my_gradle_plugin".
* _Version_ is used for the Gradle property `project.version` value in the `build.gradle` file.
For this example, enter "1.0".
![Specify the Group, Artifact, and Version IDs](img/step2_group_artifact_version.png){:width="800px"}
Click _Next_ to continue.
It’s recommended to select the `Use default gradle wrapper` option, that way IntelliJ IDEA will install everything you need to run Gradle tasks itself.
### Gradle Settings Screen
The third screen prompts for Gradle-specific settings.
All of these settings can be changed once the project is created via **Settings \| Build, Execution, Deployment \| Build Tools \| Gradle**.
Select the [default settings](https://www.jetbrains.com/help/idea/gradle-settings.html) and click _Next_ to continue.
Finally, specify a JVM Gradle will use, it can be the Project JDK. You also configure this path once the project is created via **Settings \| Build, Execution, Deployment \| Build Tools \| Gradle**.
### Project Name and Location Screen
The final Wizard screen is for setting the [project name and location](https://www.jetbrains.com/help/idea/project-name-and-location.html#Project_Name_and_Location.xml).
The _Project name_ is pre-filled with the [Artifact ID](#project-naming-screen).
![Verify the JVM is the correct version](img/step3_gradle_config.png){:width="800px"}
Note the choice of _Project format_ under _More Settings_ is somewhat superfluous.
Although an `.idea` directory or `.ipr` file is generated as the project is created and built, it is Gradle and the IntelliJ IDEA Gradle plugin that control many aspects of the project.
### 1.3 Configuring a Gradle Plugin Project
Support for Gradle-based plugin projects is provided by the IntelliJ Platform `gradle-intellij-plugin`.
Click _Finish_.
> **Note** Please make sure to always upgrade to latest version of `gradle-intellij-plugin` plugin, follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases).
### Components of a Wizard-Generated Gradle IntelliJ Platform Plugin
For the [example](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) `my_gradle_plugin`, the New Project Wizard creates the directory content shown below:
* The default IntelliJ Platform `build.gradle` file.
The contents are further discussed below.
* The Gradle Wrapper files, and in particular the `gradle-wrapper.properties` file, which specifies the version of Gradle to be used to build the plugin.
If needed, the IntelliJ IDEA Gradle plugin will download the version of Gradle specified in this file.
* The `settings.gradle` file, containing a definition of the `rootProject.name`.
* The `META-INF` directory under the default `main` [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](/basics/plugin_structure/plugin_configuration_file.md).
See the [Gradle plugin README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#gradle) for more information.
For example, to configure the **Sandbox Home** directory's location include the following in the project's `build.gradle` file:
```groovy
intellij {
sandboxDirectory = "$project.buildDir/myCustom-sandbox"
}
```text
my_gradle_plugin/
build.gradle
gradle/
wrapper/
gradle-wrapper.jar
gradle-wrapper.properties
gradlew
gradlew.bat
settings.gradle
src/
main
java/
resources/
META-INF/
plugin.xml
test
java/
resources/
```
See the [IDE Development Instances](/basics/ide_development_instance.md)
page for more information about default Sandbox Home directory locations and contents.
### 1.4 Add Gradle Support to an Existing Plugin
The New Project Wizard produces the `my_gradle_plugin` project `build.gradle` file shown below:
* There is no explicit `buildscript{}` in the file.
The IntelliJ IDEA Gradle plugin dynamically creates a `buildscript{}`.
* Two plugins to Gradle are explicitly declared:
* The [Gradle Java](https://docs.gradle.org/current/userguide/java_plugin.html) plugin.
* The [IntelliJ IDEA Gradle plugin](https://github.com/JetBrains/gradle-intellij-plugin/).
* The _Group ID_ from the Wizard [Project Naming Screen](#project-naming-screen) is the `project.group` value.
* The _Version_ from the Wizard [Project Naming Screen](#project-naming-screen) is the `project.version` value.
* The `sourceCompatibility` line is injected to enforce using Java 8 JDK to compile Java source.
* The only comment in the file is a link to the [`README.md`](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) for the IntelliJ IDEA Gradle plugin, which is a reference for the DSLs defined by the plugin.
* The value of the Setup DSL attribute `intellij.version` specifies the version of the IntelliJ Platform to be used to build the plugin.
It defaults to the version of IntelliJ IDEA that was used to run the New Project Wizard.
* The value of the Patching DSL attribute `patchPluginXml.changeNotes` is set to place holder text.
To add Gradle support to an existing plugin project, create a `build.gradle` file under the root directory, with at least the following contents:
```text
plugins {
id 'java'
id 'org.jetbrains.intellij' version '0.4.9'
}
```groovy
buildscript {
repositories {
mavenCentral()
group 'com.your.company'
version '1.0'
sourceCompatibility = 1.8
repositories {
mavenCentral()
}
dependencies {
testCompile group: 'junit', name: 'junit', version: '4.12'
}
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
version '2019.1'
}
patchPluginXml {
changeNotes """
Add change notes here.<br>
<em>most HTML tags may be used</em>"""
}
```
#### Plugin Gradle Properties and Plugin Configuration File Elements
The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective `plugin.xml` elements `<name>` and `<id>`.
There is no IntelliJ Platform-related reason they should as they serve different functions.
The `<name>` element can have nothing to do with the content root, and often is more explanatory than the `rootProject.name`.
The `<id>` is a unique identifier over all plugins, typically a concatenation of the Maven `groupId` and `artifactId`; the default Gradle `project.group` property is only the `groupId`.
## Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin
Converting a DevKit-based plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project:
* Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
* Delete all the artifacts of the DevKit-based project:
* `.idea` directory
* IML file
* `out` directory
* Arrange the existing source files within the project directory in Gradle [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) format.
* Use the New Project Wizard as though creating a [new Gradle project](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) from scratch.
* On the [Project Naming Screen](#project-naming-screen) set the values to:
* GroupID to the existing package in the initial source set.
* ArtifactID to the name of the existing plugin.
* Version to the same as the existing plugin.
* On the [Project Name and Location Screen](#project-name-and-location-screen) set the values to:
* _Project name_ to the name of the existing plugin.
(It should be pre-filled from the _ArtifactID_)
* Set the _Project location_ to the directory of the existing plugin.
* Click _Finish_ to create the new Gradle-based plugin.
* [Add more modules](https://www.jetbrains.com/help/idea/gradle.html#gradle_add_module) using Gradle [_Source Sets_](https://www.jetbrains.com/help/idea/gradle.html#gradle_source_sets) as needed.
## Running a Simple Gradle-Based IntelliJ Platform Plugin
Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-intellij-platform-plugin), some code needs to be added to provide simple functionality.
* Using the code below, add a `HelloAction.java` class to the `src/main/java/` folder.
For the sake of simplicity, no Java package is being used in this example.
```java
import com.intellij.openapi.actionSystem.*;
import com.intellij.openapi.project.Project;
import com.intellij.openapi.ui.Messages;
public class HelloAction extends AnAction {
public HelloAction() {
super("Hello");
}
}
plugins {
id "org.jetbrains.intellij" version "0.4.7"
}
apply plugin: 'idea'
apply plugin: 'org.jetbrains.intellij'
apply plugin: 'java'
intellij {
version 'IC-2016.3' //IntelliJ IDEA 2016.3 dependency; for a full list of IntelliJ IDEA releases please see https://www.jetbrains.com/intellij-repository/releases
plugins 'coverage' //Bundled plugin dependencies
pluginName 'plugin_name_goes_here'
}
group 'org.jetbrains'
version '1.2' // Plugin version
public void actionPerformed(AnActionEvent event) {
Project project = event.getProject();
Messages.showMessageDialog(project, "Hello world!", "Greeting", Messages.getInformationIcon());
}
}
```
Then, with the Gradle executable on your system `PATH`, execute the following commands on your system's command line:
* Add the code below to the `<actions>` section of the `plugin.xml` file:
```
gradle cleanIdea idea
```xml
<group id="MyPlugin.SampleMenu" text="Greeting" description="Greeting menu">
<add-to-group group-id="MainMenu" anchor="last"/>
<action id="Myplugin.Textboxes" class="HelloAction" text="Hello" description="Says hello"/>
</group>
```
This will clean any existing IntelliJ IDEA configuration files and generate a new Gradle build configuration recognized by IntelliJ IDEA. Once your project refreshes, you should be able to view the Gradle tool window displayed under **View \| Tool Windows \| Gradle**. This indicates that IntelliJ IDEA recognizes the Gradle facet.
### 1.5 Running a Simple Plugin
Now add a new `HelloAction` class to the Java folder, and `plugin.xml` and `pluginIcon.svg` files in the `META-INF` folder.
For more information about `pluginIcon.svg` files, see the [Plugin Icon](/basics/plugin_structure/plugin_icon_file.md) page.
![Gradle directory structure](img/gradle_directory_structure.png){:width="374px"}
```java
{% include /code_samples/gradle_plugin_demo/src/main/java/HelloAction.java %}
```
```java
{% include /code_samples/gradle_plugin_demo/src/main/resources/META-INF/plugin.xml %}
```
Open the Gradle tool window and search for `runIde` task. If it’s not in the list, please hit `Refresh` button on the top. Double-click on it to run it.
* Open the Gradle tool window and search for the `runIde` task.
If it’s not in the list, hit the [Refresh](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) button at the top of the Gradle window.
Or [Create a new Gradle Run Configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html).
![Gradle Tool Window](img/gradle_tasks_in_tool_window.png){:width="398px"}
Or add a new Gradle Run Configuration, configured like so:
* Double-click on the _runIde_ task to execute it.
See the IntelliJ IDEA help for more information about [Working with Gradle tasks](https://www.jetbrains.com/help/idea/gradle.html#96bba6c3).
![Gradle Run Configuration](img/gradle_run_config.png){:width="800px"}
Launch the new Gradle Run Configuration. From the Run Window, the following output should be visible.
![Gradle task output](img/launched.png){:width="800px"}
Finally, when the IDE launches, there should be a new menu to the right of the **Help** menu. Your plugin is now configured on Gradle.
Finally, when `my_gradle_plugin` launches in the IDE development instance, there should be a new **Greeting** main menu to the right of the **Help** menu.