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

One sentence per line.

Browse Source
This commit is contained in:
JohnHake 2019-05-01 12:47:36 -07:00
parent 55a7bfd75a
commit 21c881a4c0
3 changed files with 55 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
tutorials/build_system.md
View File

@ -2,15 +2,13 @@
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.
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.
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.
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.
* [1. Getting Started](build_system/prerequisites.md)
* [2. Deploying a plugin](build_system/deployment.md)

34
tutorials/build_system/deployment.md
View File

@ -2,8 +2,9 @@
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).
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).
### 2.0 Add your account credentials
@ -11,7 +12,8 @@ In order to deploy a plugin to the plugin repository, you will first need to sup
We will describe three options to do so: using only the Gradle properties, using environment variables and using arguments to the Gradle task.
#### Using the Gradle properties file
You can store the credentials in the [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties). It is crucial that you do not check these credentials into source control.
You can store the credentials in the [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties).
It is crucial that you do not check these credentials into source control.
To do this, place the following information inside a file called `gradle.properties` under your project's root directory, or inside `GRADLE_HOME/gradle.properties`.
@ -29,7 +31,8 @@ publishPlugin {
}
```
If you place a `gradle.properties` file in your project's root directory, please ensure that this file is ignored by your version control tool. For example in Git, you can add the following line to your `.gitignore` file:
If you place a `gradle.properties` file in your project's root directory, please ensure that this file is ignored by your version control tool.
For example in Git, you can add the following line to your `.gitignore` file:
```
gradle.properties
@ -53,7 +56,9 @@ Note that also in this case you still need to put some default values in your Gr
### 2.1 Configure your plugin
The gradle-intellij-plugin provides a number of [configuration options](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for customizing how Gradle builds your plugin. One of the most important is the `version`. By default, if you modify the `version` in your build script, the Gradle plugin will automatically update the `<version>` in your `plugin.xml` file.
The gradle-intellij-plugin provides a number of [configuration options](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for customizing how Gradle builds your plugin.
One of the most important is the `version`.
By default, if you modify the `version` in your build script, the Gradle plugin will automatically update the `<version>` in your `plugin.xml` file.
The Gradle plugin will also update the `<idea-version since-build=.../>` values within the `plugin.xml` file to match the `intellij.version`, valid until the last release in the current major version, however you can disable this feature by setting the `intellij.updateSinceUntilBuild` option to `false`.
@ -74,19 +79,23 @@ group 'com.jetbrains'
version '1.2' // Update me!
```
When you run `gradle runIde` with a build script containing the above snippet, Gradle will download the appropriate version of IntelliJ IDEA from either a [Snapshot](https://www.jetbrains.com/intellij-repository/snapshots) (time-based) or [Release](https://www.jetbrains.com/intellij-repository/releases) (version based) repository, configure the plugin sandbox, install your plugin, and launch a new instance of the IDE. This task can be run directly from the command line, without any prior tooling assistance.
When you run `gradle runIde` with a build script containing the above snippet, Gradle will download the appropriate version of IntelliJ IDEA from either a [Snapshot](https://www.jetbrains.com/intellij-repository/snapshots) (time-based) or [Release](https://www.jetbrains.com/intellij-repository/releases) (version based) repository, configure the plugin sandbox, install your plugin, and launch a new instance of the IDE.
This task can be run directly from the command line, without any prior tooling assistance.
### 2.3 Deploy your plugin
The first step when deploying a plugin is to confirm that it works correctly. You may wish to verify this by [installing your plugin from disk](https://www.jetbrains.com/help/idea/managing-plugins.html) on a fresh instance of your target IDE(s). Once you are confident the plugin works as intended, make sure the plugin version is updated, as the JetBrains Plugin repository will not accept multiple artifacts with the same version. To deploy a new version of your plugin to the JetBrains plugin repository, execute the following Gradle command:
The first step when deploying a plugin is to confirm that it works correctly.
You may wish to verify this by [installing your plugin from disk](https://www.jetbrains.com/help/idea/managing-plugins.html) on a fresh instance of your target IDE(s). Once you are confident the plugin works as intended, make sure the plugin version is updated, as the JetBrains Plugin repository will not accept multiple artifacts with the same version. To deploy a new version of your plugin to the JetBrains plugin repository, execute the following Gradle command:
```bash
gradle publishPlugin
```
Now check that the most recent version of your plugin appears on the [Plugin Repository](https://plugins.jetbrains.com/). If successfully deployed, any users who currently have your plugin installed on an eligible version of the IntelliJ Platform will be notified of a new update available on the following restart.
Now check that the most recent version of your plugin appears on the [Plugin Repository](https://plugins.jetbrains.com/).
If successfully deployed, any users who currently have your plugin installed on an eligible version of the IntelliJ Platform will be notified of a new update available on the following restart.
You may also deploy plugins to a release channel of your choosing, by configuring the `publishPlugin.channels` property. For example:
You may also deploy plugins to a release channel of your choosing, by configuring the `publishPlugin.channels` property.
For example:
```groovy
publishPlugin {
@ -94,7 +103,12 @@ publishPlugin {
}
```
When empty, this will use the default plugin repository, available to all [JetBrains plugin repository](https://plugins.jetbrains.com/) users. However, you can publish to an arbitrarily-named channel. These non-default release channels are treated as separate repositories for all intents and purposes. When using a non-default release channel, users will need to add a new [custom plugin repository](https://www.jetbrains.com/help/idea/managing-plugins.html#repos) to install your plugin. For example, if you specify `publishPlugin.channels 'canary'`, then users will need to add the `https://plugins.jetbrains.com/plugins/canary/list` repository to install the plugin and receive updates. Popular channel names include:
When empty, this will use the default plugin repository, available to all [JetBrains plugin repository](https://plugins.jetbrains.com/) users.
However, you can publish to an arbitrarily-named channel.
These non-default release channels are treated as separate repositories for all intents and purposes.
When using a non-default release channel, users will need to add a new [custom plugin repository](https://www.jetbrains.com/help/idea/managing-plugins.html#repos) to install your plugin.
For example, if you specify `publishPlugin.channels 'canary'`, then users will need to add the `https://plugins.jetbrains.com/plugins/canary/list` repository to install the plugin and receive updates.
Popular channel names include:
* `alpha`: https://plugins.jetbrains.com/plugins/alpha/list
* `beta`: https://plugins.jetbrains.com/plugins/beta/list

44
tutorials/build_system/prerequisites.md
View File

@ -2,41 +2,42 @@
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).
Adding Gradle build support to an IntelliJ Platform Plugin requires a recent distribution of the Gradle build system and IntelliJ IDEA (Community or Ultimate).
### 1.0 Download and Install IntelliJ IDEA
Download and install either IntelliJ IDEA Ultimate or the IntelliJ IDEA Community Edition.
Download and install either IntelliJ IDEA Ultimate or the IntelliJ IDEA Community Edition.
### 1.1 Ensure that 'Gradle' and 'Plugin DevKit' Plugins are Enabled
You can verify that the plugins are enabled by visiting **Settings \| Plugins**.
You can verify that the plugins are enabled by visiting **Settings \| Plugins**.
![Ensure the Gradle plugin is enabled](img/step0_gradle_enabled.png){:width="858px"}
### 1.2 Create a Plugin Project from Scratch
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.
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.
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".
![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:
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:
![Specify the Group, Artifact, and Version IDs](img/step2_group_artifact_version.png){:width="800px"}
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.
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.
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**.
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**.
![Verify the JVM is the correct version](img/step3_gradle_config.png){:width="800px"}
### 1.3 Configuring a Gradle Plugin Project
Support for Gradle-based plugin projects is provided by the IntelliJ Platform `gradle-intellij-plugin`.
Support for Gradle-based plugin projects is provided by the IntelliJ Platform `gradle-intellij-plugin`.
> **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).
@ -47,8 +48,7 @@ intellij {
sandboxDirectory = "$project.buildDir/myCustom-sandbox"
}
```
See the [IDE Development Instances](/basics/ide_development_instance.md)
page for more information about default Sandbox Home directory locations and contents.
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
@ -85,12 +85,14 @@ Then, with the Gradle executable on your system `PATH`, execute the following co
gradle cleanIdea idea
```
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.
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.
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"}
@ -102,7 +104,9 @@ For more information about `pluginIcon.svg` files, see the [Plugin Icon](/basics
{% 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 `runIde` task.
If it’s not in the list, please hit `Refresh` button on the top.
Double-click on it to run it.
![Gradle Tool Window](img/gradle_tasks_in_tool_window.png){:width="398px"}
@ -110,8 +114,10 @@ Or add a new Gradle Run Configuration, configured like so:
![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.
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 the IDE launches, there should be a new menu to the right of the **Help** menu.
Your plugin is now configured on Gradle.