minor cleanups

This commit is contained in:
Karol Lewandowski 2022-03-11 14:14:16 +01:00
parent 0e9cd37fef
commit 968b2dabed
4 changed files with 56 additions and 25 deletions

View File

@ -15,11 +15,13 @@ Please see the guide page for manually [publishing a plugin](publishing_plugin.m
{type="warning"}
## Building Distribution
For initial upload, manual distribution or local installation, invoke the `buildPlugin` Gradle task to create the plugin distribution.
The resulting ZIP file is located in <path>build/distributions</path> and can then be installed via drag & drop (or using [plugin manager](https://www.jetbrains.com/help/idea/managing-plugins.html#installing-plugins-from-disk))
or uploaded to a [custom plugin repository](update_plugins_format.md).
## Providing Your Personal Access Token to Gradle
To deploy a plugin to the JetBrains Marketplace, you need to supply your Personal Access Token, which you can find on your profile page, in [My Tokens](https://plugins.jetbrains.com/author/me/tokens) section.
To create a new token, provide its name and click the <control>Generate Token</control> button.
@ -35,6 +37,7 @@ This section describes two options to supply your _Personal Access Token_ via Gr
* Parameters to the Gradle task.
### Using Environment Variables
Start by defining an environment variable such as:
```bash
@ -74,6 +77,7 @@ publishPlugin {
Note that you still need to put some default values (can be empty) in the Gradle properties because otherwise, you will get a compilation error.
### Using Parameters for the Gradle Task
Like using environment variables, you can also pass your token as a parameter to the Gradle task.
For example, you can provide the parameter
@ -85,6 +89,7 @@ on the command line or by putting it in the arguments of your Gradle run configu
Note that also, in this case, you still need to put some default values in your Gradle properties.
## Deploying a Plugin with Gradle
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).
@ -96,6 +101,7 @@ In version `1.x`, the Gradle IntelliJ Plugin provides the `signPlugin` task, whi
For more details on generating a proper certificate and configuring the `signPlugin` task, check the [Plugin Signing](plugin_signing.md) article.
### Publishing a Plugin
Once you are confident the plugin works as intended, make sure the plugin version is updated, as the JetBrains Marketplace won't accept multiple artifacts with the same version.
To deploy a new version of your plugin to the JetBrains Marketplace, invoke the `publishPlugin` Gradle task.
@ -104,6 +110,7 @@ Now check the most recent version of your plugin on the [JetBrains Marketplace](
If successfully deployed, any users who currently have your plugin installed on an available version of the IntelliJ Platform are notified of a new update available as soon as the update has been verified.
### Specifying a Release Channel
You may also deploy plugins to a release channel of your choosing, by configuring the `publishPlugin.channels` property.
For example:

View File

@ -5,14 +5,15 @@
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](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](intellij_platform.md#open-source) section.
The [](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 [](intellij_platform.md#open-source) section.
> When adding additional repositories to your Gradle build script, always use HTTPS protocol.
>
{type="warning"}
## Overview of the Gradle Plugin
The Gradle plugin is built from the open-source project [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin).
This plugin adds Gradle tasks that enable developing IntelliJ Platform plugins.
The [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) file has a reference for configuring these tasks.
@ -31,9 +32,11 @@ When getting started, there are several items to note on the README page:
* Almost every Gradle plugin attribute has a default value that will work to get started on a Gradle-based IntelliJ Platform plugin project.
## Guide to Configuring Gradle Plugin Functionality
This section presents a guided tour of Gradle plugin attributes to achieve the commonly desired functionality.
### Configuring the Gradle Plugin for Building IntelliJ Platform Plugin Projects
By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.
> Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the <path>build.gradle</path> file (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)).
@ -44,14 +47,16 @@ If a matching 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 Configuration
Explicitly setting the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) attributes `intellij.version` and `intellij.type` tells the Gradle plugin to use that configuration of the IntelliJ Platform to create the plugin project.
All available platform versions can be browsed in the [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md).
All available platform versions can be browsed in the [](intellij_artifacts.md).
If the chosen platform version is not available in the repositories, or a local installation of the target IDE 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.
#### 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`.
@ -61,20 +66,24 @@ Note that this attribute describes a dependency so that the Gradle plugin can fe
The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (<path>plugin.xml</path>) file as described in [Plugin Dependencies](plugin_dependencies.md#3-dependency-declaration-in-pluginxml).
### Configuring the Gradle Plugin for Running IntelliJ Platform Plugin Projects
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 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 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.
Setting the [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideDir` will define an IDE to be used for the Development Instance.
This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](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](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).
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 specified 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 use by the IDE Development Instance.
The location of the [sandbox home](ide_development_instance.md#the-development-instance-sandbox-directory) directory and its subdirectories can be controlled with Gradle plugin attributes.
@ -86,6 +95,7 @@ The storage location of downloaded IDE versions and components defaults to the G
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-gradle-plugin-for-building-intellij-platform-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.
Standardizing the versions of the Gradle plugin and Gradle system across projects will minimize the time spent downloading versions.
@ -94,6 +104,7 @@ The plugin version is defined in the `plugins {}` section of a project's <path>b
The version of Gradle is defined in <path>$PROJECT_ROOT$/gradle/wrapper/gradle-wrapper.properties</path>.
### Patching the Plugin Configuration File
A plugin project's <path>plugin.xml</path> file has element values that are "patched" at build time from the attributes of the `patchPluginXml` task ([Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin#patching-dsl)).
As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's <path>plugin.xml</path> file:
* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in <path>plugin.xml</path> _regardless of whether the `patchPluginXml` task appears in the <path>build.gradle</path> file_.
@ -105,8 +116,8 @@ As many as possible of the attributes in the Patching DSL will be substituted in
* For **no substitution** of the `<idea-version>` element's `since-build` and `until-build` attributes, one of the following must appear in the <path>build.gradle</path> file:
* Either set `intellij.updateSinceUntilBuild = false`, which will disable substituting both `since-build` and `until-build` attributes,
A best practice to avoid confusion is to replace the elements in <path>plugin.xml</path> 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 best practice to avoid confusion is to replace the elements in <path>plugin.xml</path> 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 `patchPluginXml` attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements.
@ -122,22 +133,26 @@ By default, if you modify `project.version` in <path>build.gradle</path>, the Gr
This practice keeps all version declarations synchronized.
### Verifying Plugin
The Gradle plugin provides two tasks that allow for running integrity and compatibility tests:
- `verifyPlugin` - validates completeness and contents of <path>plugin.xml</path> descriptors as well as plugins archive structure,
- `runPluginVerifier` - runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.
* `verifyPlugin` - validates completeness and contents of <path>plugin.xml</path> descriptors as well as plugin's archive structure,
* `runPluginVerifier` - runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.
Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against.
See [Verifying Compatibility](api_changes_list.md#verifying-compatibility) for more information.
### 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.
Please review the [](deployment.md) page before using the [Publishing DSL](https://github.com/JetBrains/gradle-intellij-plugin#publishing-dsl) attributes.
That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials.
## Common Gradle Plugin Configurations for Development
Different combinations of Gradle plugin attributes are needed to create the desired build or IDE Development Instance environment.
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 use for building the plugin project](#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects); this is the desired version of the IntelliJ Platform.
This can be EAP (default) or determined from the [build number ranges](build_number_ranges.md).
@ -150,5 +165,6 @@ IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward
* Set the appropriate attributes for [patching the plugin.xml file](#patching-the-plugin-configuration-file).
### Plugins Targeting Alternate IntelliJ Platform-Based IDEs
Gradle also supports developing plugins to run in IDEs that are based on the IntelliJ Platform.
For more information, see the [Developing for Multiple Products](dev_alternate_products.md) page of this guide.

View File

@ -16,17 +16,19 @@ To verify these plugins are installed and enabled, see the help section about [M
{type="warning"}
## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard
Creating new Gradle-based IntelliJ Platform plugin projects is performed 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.
Before creating a new Gradle project, familiarize yourself with the 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.
Before creating a new Gradle project, familiarize yourself with the [Creating a new Gradle project](https://www.jetbrains.com/help/idea/getting-started-with-gradle.html#create_gradle_project) help topic, which is a tutorial for creating general Gradle projects in IntelliJ IDEA.
This page emphasizes the steps in the process of creating IntelliJ Platform plugin projects that are Gradle-based.
Additionally, screencast [Working with Gradle in IntelliJ IDEA](https://www.youtube.com/watch?v=6V6G3RyxEMk) offers a thorough introduction.
Additionally, the [Working with Gradle in IntelliJ IDEA](https://www.youtube.com/watch?v=6V6G3RyxEMk) screencast offers a thorough introduction.
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 two screens.
### New Project Configuration Screen
On the first screen, the type of project is configured:
* From the project type pane on the left, choose <control>Gradle</control>.
* Specify the <control>Project SDK</control> based on the **Java 8** JDK.
@ -50,10 +52,11 @@ Then click _Next_:
![Select Gradle in the Project Creation Wizard](step1_new_gradle_project.png){width="800"}
### Project Naming/Artifact Coordinates Screen
Expand the <control>Artifact Coordinates</control> section and specify a [GroupId, ArtifactId, and 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.
* <control>GroupId</control> is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's <path>build.gradle</path> file.
For this example, enter `com.your.company`.
* <control>ArtifactId</control> is the default name of the project JAR file (without version).
* <control>ArtifactId</control> is the default name of the project JAR file (without a version).
It is also used for the Gradle property `rootProject.name` value in the project's <path>settings.gradle</path> file.
For this example, enter `my_gradle_plugin`.
* <control>Version</control> is used for the Gradle property `project.version` value in the <path>build.gradle</path> file.
@ -64,6 +67,7 @@ The <control>Name</control> field is synced automatically with the specified <co
Specify the path for the new project in <control>Location</control> and click <control>Finish</control> to continue and generate the project.
### 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 following directory content:
```text
@ -102,8 +106,8 @@ The generated `my_gradle_plugin` project <path>build.gradle</path> file:
```groovy
plugins {
id 'java'
id 'org.jetbrains.intellij' version '1.4.0'
id 'java'
id 'org.jetbrains.intellij' version '1.4.0'
}
group 'com.your.company'
@ -111,20 +115,20 @@ version '1.0'
sourceCompatibility = 1.8
repositories {
mavenCentral()
mavenCentral()
}
dependencies {
testImplementation group: 'junit', name: 'junit', version: '4.13.2'
testImplementation group: 'junit', name: 'junit', version: '4.13.2'
}
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
version = '2020.1.3'
version = '2020.1.3'
}
patchPluginXml {
changeNotes = """
Add change notes here.<br/>
<em>most HTML tags may be used</em>"""
changeNotes = """
Add change notes here.<br/>
<em>most HTML tags may be used</em>"""
}
```
@ -137,9 +141,10 @@ patchPluginXml {
* 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 gradle-intellij-plugin, which is a reference for its configuration DSL.
* 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 a place holder text.
* The value of the Patching DSL attribute `patchPluginXml.changeNotes` is set to a placeholder text.
#### Plugin Gradle Properties and Plugin Configuration File Elements
The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective [plugin configuration file](plugin_configuration_file.md) <path>plugin.xml</path> elements `<name>` and `<id>`.
There is no IntelliJ Platform-related reason they should as they serve different functions.
@ -162,26 +167,29 @@ Converting a [DevKit-based](using_dev_kit.md) plugin project to a Gradle-based p
* <path>out</path> directory
* Arrange the existing source files within the project directory in the 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/Artifact Coordinates Screen](#project-namingartifact-coordinates-screen) set the values to:
* On the [Project Naming/Artifact Coordinates Screen](#project-namingartifact-coordinates-screen) set the values of:
* <control>GroupId</control> to the existing package in the initial source set.
* <control>ArtifactId</control> to the name of the existing plugin.
* <control>Version</control> to the same as the existing plugin.
* <control>Name</control> to the name of the existing plugin.
(It should be pre-filled from the <control>ArtifactId</control>)
* Set the <control>Location</control> to the directory of the existing plugin.
* <control>Location</control> to the directory of the existing plugin.
* Click <control>Finish</control> 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
Gradle projects are run from the IDE's Gradle Tool window.
### Adding Code to the Project
Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-intellij-platform-plugin), some code can be added to provide simple functionality.
See the [Creating Actions](working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action.
### Executing the Plugin
Open the Gradle tool window and search for the <control>runIde</control> task:
* If its 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 tool window.
* If it's not on the list, hit the [Refresh](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) button at the top of the Gradle tool window.
* Or [Create a new Gradle Run Configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html).
![Gradle Tool Window](gradle_tasks_in_tool_window.png){width="398"}

View File

@ -7,7 +7,7 @@ The plugin takes care of the dependencies of your plugin project — both the ba
It provides tasks to run the IDE with your plugin and to package and publish your plugin to the [JetBrains Marketplace](https://plugins.jetbrains.com).
To make sure that a plugin is not affected by [API changes](api_changes_list.md), which may happen between major releases of the platform, you can quickly verify your plugin against other IDEs and releases.
> [IntelliJ Platform Plugin Template](github_template.md) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions.
> [](github_template.md) makes it easier to create and maintain your IDE plugins, having the Gradle plugin already integrated and CI covered with GitHub Actions.
>
{type="tip"}