diff --git a/code_samples/README.md b/code_samples/README.md index 63463f30d..3482627ab 100644 --- a/code_samples/README.md +++ b/code_samples/README.md @@ -32,7 +32,7 @@ It describes definitions of the actions, extensions, or listeners provided by th Please see [Code Samples][docs:code-samples] topic on how to import and run code samples. -In the following table, you may find all available samples provided in the separated directories as stand-alone projects available for running with the Gradle `:runIde` task. +In the following table, you may find all available samples provided in the separated directories as stand-alone projects available for running with the Gradle [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task. | Code Sample | Description | |------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/ijs.tree b/ijs.tree index da5103435..e33bc8ff4 100644 --- a/ijs.tree +++ b/ijs.tree @@ -375,4 +375,10 @@ + + + + + + diff --git a/reference_guide/api_changes_list.md b/reference_guide/api_changes_list.md index 036a8a4ef..3bcac3c27 100644 --- a/reference_guide/api_changes_list.md +++ b/reference_guide/api_changes_list.md @@ -71,7 +71,7 @@ Compatibility with newer IDEs can easily be verified for plugins hosted on the [ For local verification or non-public plugins, [intellij-plugin-verifier](https://github.com/JetBrains/intellij-plugin-verifier) can be used standalone as well. -Integration in [Gradle build](gradle_build_system.md) is available using the `runPluginVerifier` task, please see [Gradle IntelliJ Plugin - Plugin Verifier DSL](https://github.com/JetBrains/gradle-intellij-plugin#plugin-verifier-dsl) for details. +Integration in [Gradle build](gradle_build_system.md) is available using the [`runPluginVerifier`](tools_gradle_intellij_plugin.md#runpluginverifier-task) task, please see [Gradle IntelliJ Plugin - Plugin Verifier](tools_gradle_intellij_plugin.md#runpluginverifier-task) for details. You can easily integrate it within your CI by running that task as another quality check step. Check the IntelliJ Platform Plugin Template [GitHub workflow configuration file](https://github.com/JetBrains/intellij-platform-plugin-template/blob/main/.github/workflows/build.yml) as sample. diff --git a/reference_guide/api_changes_list_2020.md b/reference_guide/api_changes_list_2020.md index f1ac378c5..559d1c1f7 100644 --- a/reference_guide/api_changes_list_2020.md +++ b/reference_guide/api_changes_list_2020.md @@ -72,7 +72,7 @@ Please see [Incompatible API Changes](api_changes_list.md) on how to verify comp > Java 11 is required ([blog post](https://blog.jetbrains.com/platform/2020/09/intellij-project-migrates-to-java-11/)) when targeting 2020.3 and later only. > -> Please make sure to always upgrade `gradle-intellij-plugin` to the latest version [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases) +> Please make sure to always upgrade [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) to the latest version [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases) > {type="note"} diff --git a/topics/appendix/resources/explore_api.md b/topics/appendix/resources/explore_api.md index 8ff86ba84..b90e3d307 100644 --- a/topics/appendix/resources/explore_api.md +++ b/topics/appendix/resources/explore_api.md @@ -88,7 +88,7 @@ Many developers keep the [IntelliJ Community source code](https://github.com/JetBrains/intellij-community) open in a separate window while working on their plugin. Others simply search the source code of the IntelliJ Platform that is attached by default when using a -[Gradle-based plugin project](https://github.com/JetBrains/gradle-intellij-plugin#infrastructure-properties). +[Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md)-based project. While both methods work, it should be noted that developing plugins without inspecting the IntelliJ Platform code is nearly impossible, and all of the tips below assume that you have the source code available. diff --git a/topics/appendix/tools/tools_gradle_intellij_plugin.md b/topics/appendix/tools/tools_gradle_intellij_plugin.md new file mode 100644 index 000000000..406d03ea9 --- /dev/null +++ b/topics/appendix/tools/tools_gradle_intellij_plugin.md @@ -0,0 +1,1356 @@ +[//]: # (title: Gradle IntelliJ Plugin) + + + +The Gradle IntelliJ Plugin is a plugin for the Gradle build system to help configuring your environment for building, testing, verifying, and publishing plugins for IntelliJ-based IDEs. + +> Current Gradle IntelliJ Plugin version is [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases) +> +{type="note"} + +This plugin allows you to build plugins for IntelliJ Platform using specified IntelliJ SDK and bundled or third-party plugins. + +The plugin adds extra IntelliJ-specific dependencies, patches `processResources` tasks to fill some tags (name, version) in [plugin.xml](plugin_configuration_file.md) with appropriate values, patches compile tasks to instrument code with nullability assertions and forms classes made with IntelliJ GUI Designer and provides some build steps which might be helpful while developing plugins for IntelliJ platform. + + +## Usage +To enable this plugin in your Gradle-based project, add the following entry to the `plugins` section: + + + + +```kotlin +plugins { + id("org.jetbrains.intellij") version "..." +} +``` + + + + +```groovy +plugins { + id "org.jetbrains.intellij" version "..." +} +``` + + + + +When upgrading to `1.x` version, please make sure to follow [migration guide](https://lp.jetbrains.com/gradle-intellij-plugin) to adjust your existing build script. + +> Gradle JVM must be set to `Java 11` (see Settings/Preferences | Build, Execution, Deployment | Build Tools | Gradle) +> +{type="tip"} + +> This project requires `Gradle 6.7` or newer, however it is recommended to use the latest Gradle available. +> Update it with: +> ```Bash +> ./gradlew wrapper --gradle-version=VERSION +> ``` +> +> See also: [Gradle Installation](https://gradle.org/install/) guide. +{type="tip"} + +### Snapshot Release +The Snapshot release is a pre-release version built nightly from the latest main branch – as it is built every day using the same version number, it's not recommended to use it in production. + +For switching to the snapshot release, point Gradle to the dedicated snapshot repository by adding an entry to the Gradle settings file. + +> Current Gradle IntelliJ Plugin Snapshot version is [![GitHub Snapshot Release](https://img.shields.io/nexus/s/org.jetbrains.intellij/org.jetbrains.intellij.gradle.plugin?server=https://oss.sonatype.org)](https://github.com/jetbrains/gradle-intellij-plugin/releases) +> +{type="note"} + + + + +`build.gradle.kts` +```kotlin +plugins { + id("org.jetbrains.intellij") version "..." +} +``` + +`settings.gradle.kts` +```kotlin +pluginManagement { + repositories { + maven("https://oss.sonatype.org/content/repositories/snapshots/") + gradlePluginPortal() + } +} +``` + + + +`build.gradle` +```groovy +plugins { + id "org.jetbrains.intellij" version "..." +} +``` + +`settings.gradle` +```groovy +pluginManagement { + repositories { + maven { + url 'https://oss.sonatype.org/content/repositories/snapshots/' + } + gradlePluginPortal() + } +} +``` + + + + + +## IntelliJ Extension +After the Gradle IntelliJ Plugin is applied, the `intellij` extension can be used to configure the plugin and common settings of the provided tasks. + +It is mandatory to specify at least the [`intellij.version`](#intellij-extension-version) property. + +**Example:** + + + + + +```kotlin +intellij { + version.set("2022.1.1") + type.set("IU") + plugins.set(listOf("com.jetbrains.php:221.5787.21")) +} +``` + + + + +```groovy +intellij { + version = "2022.1.1" + type = "IU" + plugins = ["com.jetbrains.php:221.5787.21"] +} +``` + + + + + +### version +{id="intellij-extension-version"} + +All available JetBrains IDEs versions can be found at [IntelliJ Artifacts](intellij_artifacts.md) page. + +The version of the IntelliJ Platform IDE that will be used to build the plugin. +Please see [Plugin Compatibility](plugin_compatibility.md) topic in SDK docs for more details. + +**Required** + +**Type:** `String` + +**Acceptable values:** +- version number: `2022.1.1` or `IC-2022.1.1` +- build number: `221.5080.210` or `IC-221.5080.210` +- snapshot: `221-EAP-SNAPSHOT` or `LATEST-EAP-SNAPSHOT` + +> The _version number_ format is the most common option for specifying the version of the IntelliJ Platform. +> Other formats should be used only when your plugin relies on specific parts of the targeted IDE or early-adopting EAP releases. +> +{type="tip"} + + +### type +{id="intellij-extension-type"} + +The type of the IntelliJ-based IDE distribution. +The type may also be specified as a prefix of the value for the [`intellij.version`](#intellij-extension-version) property instead. + +**Type:** `String` + +**Default value:** `IC` + +**Acceptable values:** +- `IC` - [IntelliJ IDEA Community Edition](idea.md) +- `IU` - [IntelliJ IDEA Ultimate Edition](idea.md) +- `CL` - [CLion](clion.md) +- `PY` - [PyCharm Professional Edition](pycharm.md) +- `PC` - [PyCharm Community Edition](pycharm.md) +- `RD` - [Rider](rider.md) +- `GO` - [GoLand](goland.md) +- `JPS` - JPS-only +- `GW` - Gateway + + +### pluginName +{id="intellij-extension-pluginname"} + +The name of the generated ZIP archive distribution: `/build/distributions/PluginName-1.0.0.zip`. + +**Type:** `String` + +**Default value:** `${project.name}` + + +### localPath +{id="intellij-extension-localpath"} + +The path to the locally installed IDE distribution that should be used to build the plugin. +Using the `intellij.localPath` allows to build the plugin using IDE that is not available in the [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md). + +**Type:** `String` + +**Default value:** `null` + +**Samples:** +- `C:\Users\user\AppData\Local\JetBrains\Toolbox\apps\IDEA-U\ch-0\211.7142.45` +- `/Applications/Android Studio 4.2 Preview.app/Contents` +- `/home/user/idea-IC-181.4445.78` + +> `intellij.version` and `intellij.localPath` must not be specified at the same time. +> +{type="warning"} + + +### localSourcesPath +{id="intellij-extension-localsourcespath"} + +The path to local archive with IDE sources. +Used for resolving source files of the locally installed IDE distribution when [`intellij.localPath`](#intellij-extension-localpath) is specified. + +**Type:** `String` + +**Default value:** `null` + + +### plugins +{id="intellij-extension-plugins"} + +The list of bundled IDE plugins and plugins from [JetBrains Marketplace](https://plugins.jetbrains.com) or configured [`intellij.pluginsRepositories`](#intellij-extension-pluginsrepositories). + +Please see [Plugin Dependencies](plugin_dependencies.md) for more details. + +Notes: +- For plugins from [JetBrains Marketplace](https://plugins.jetbrains.com), use format `pluginId:version`. +- For bundled plugins, version must be omitted: e.g. `org.intellij.groovy`. +- For subprojects, use project reference `project(':subproject')`. +- If you need to refer plugin's classes from your project, you also have to define a dependency in your [plugin.xml](plugin_configuration_file.md) file. + +**Type:** `List` + +**Default value:** `[]` + +**Acceptable values:** +- `org.plugin.id:version[@channel]` format, `String` type: + - `org.intellij.plugins.markdown:8.5.0` + - `org.intellij.scala:2017.2.638@nightly` +- `bundledPluginName` format, `String` type: + - `android` + - `Groovy` +- `project(...)` format, `Project` type: + - `project(":projectName")` + - `project(":plugin-subproject")` + + +### updateSinceUntilBuild +{id="intellij-extension-updatesinceuntilbuild"} + +Defines if the [plugin.xml](plugin_configuration_file.md) should be patched with the values of [`patchPluginXml.sinceBuild`](#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](#patchpluginxml-task-untilbuild) properties. + +**Type:** `Boolean` + +**Default value:** `true` + + +### sameSinceUntilBuild +{id="intellij-extension-samesinceuntilbuild"} + +Patches [plugin.xml](plugin_configuration_file.md) with the [`patchPluginXml.untilBuild`](#patchpluginxml-task-untilbuild) with the value of [`patchPluginXml.sinceBuild`](#patchpluginxml-task-sincebuild) used with `*` wildcard, like `sinceBuild.*`, e.g., `221.*`. + +Notes: +- Useful for building plugins against EAP IDE builds. +- If [`patchPluginXml.untilBuild`](#patchpluginxml-task-untilbuild) has a value set, then [`intellij.sameSinceUntilBuild`](#intellij-extension-samesinceuntilbuild) is ignored. + +**Type:** `Boolean` + +**Default value:** `false` + + +### instrumentCode +{id="intellij-extension-instrumentcode"} + +Instrument Java classes with [nullability](https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html) assertions and compile forms created by [IntelliJ GUI Designer](https://www.jetbrains.com/help/idea/gui-designer-basics.html). + +**Type:** `Boolean` + +**Default value:** `true` + + +### sandboxDir +{id="intellij-extension-sandboxdir"} + +The path of [sandbox directory](ide_development_instance.md#the-development-instance-sandbox-directory) that is used for running IDE with developed plugin. + +**Type:** `String` + +**Default value:** `${project.buildDir}/idea-sandbox` + + +### intellijRepository +{id="intellij-extension-intellijrepository"} + +The IntelliJ-based IDE distributions repository URL. + +**Type:** `String` + +**Default value:** `https://cache-redirector.jetbrains.com/www.jetbrains.com/intellij-repository` + + +### pluginsRepositories +{id="intellij-extension-pluginsrepositories"} + +Configures repositories for downloading plugin dependencies. + +**Type:** `PluginsRespositoryConfiguration` + +**Default value:** `pluginsRepositories { marketplace() }` + +**Acceptable values:** +- `marketplace()` - use Maven repository with plugins listed in [JetBrains Marketplace](https://plugins.jetbrains.com) +- `maven(repositoryUrl)` - use custom Maven repository with plugins +- `maven { repositoryUrl }` - use custom Maven repository with plugins where you can configure additional parameters (credentials, authentication and etc.) +- `custom(pluginsXmlUrl)` - use [custom plugin repository](update_plugins_format.md) + + +### jreRepository +{id="intellij-extension-jrerepository"} + +URL of repository for downloading [JetBrains Runtime](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). + +**Type:** `String` + +**Default value:** `null` + + +### ideaDependencyCachePath +{id="intellij-extension-ideadependencycachepath"} + +Path to the directory where IDE dependency cache is stored. +If not set, the dependency will be extracted next to the downloaded ZIP archive in [Gradle cache](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home) directory. + +**Type:** `String` + +**Default value:** `null` + + +### downloadSources +{id="intellij-extension-downloadsources"} + +Download IntelliJ Platform sources. +It is enabled by default if the `CI` environment variable is not set – which is present on Continuous Integration environments, like GitHub Actions, TeamCity, and others. + +**Type:** `Boolean` + +**Default value:** `!System.getenv().containsKey("CI")` + + +### configureDefaultDependencies +{id="intellij-extension-configuredefaultdependencies"} + +If enabled, automatically configures the default IntelliJ Platform dependencies in the current project. +Otherwise, the `DependenciesUtils.intellij`, `DependenciesUtils.intellijPlugin`, and `DependenciesUtils.intellijPlugins` functions could be used for an explicit configuration. + +**Type:** `Boolean` + +**Default value:** `true` + + +### extraDependencies +{id="intellij-extension-extradependencies"} + +Configure extra dependency artifacts from the IntelliJ repository. +The dependencies on them could be configured only explicitly using the `DependenciesUtils.intellijExtra` function in the `dependencies` block. + +**Type:** `List` + +**Default value:** `[]` + + +## buildPlugin Task +Assembles plugin and prepares ZIP archive for [deployment](deployment.md). + +### archiveBaseName +{id="buildplugin-task-archivebasename"} + +The base name of the ZIP archive. + +This task is preconfigured automatically and takes the output artifacts of [`prepareSandbox`](#preparesandbox-task) and [`jarSearchableOptions`](#jarsearchableoptions-task) tasks as an input. + +**Type:** `String` + +**Default value:** `${prepareSandboxTask.pluginName}` + + +## buildSearchableOptions Task +Builds an index of UI components (searchable options) for the plugin. +This task runs a headless IDE instance to collect all the available options provided by the plugin's [settings](settings.md). + +Note, that this is a [`runIde`](#runide-task)-based task with predefined arguments and all properties of the [`runIde`](#runide-task) task are also applied to [`buildSearchableOptions`](#buildsearchableoptions-task) tasks. + +> If your plugin doesn't implement custom settings, you may [disable it](tools_gradle_intellij_plugin_faq.md#how-to-disable-building-searchable-options). +> +{type="tip"} + + +### outputDir +{id="buildsearchableoptions-task-outputdir"} + +**Type:** `File` + +**Default value:** `build/searchableOptions` + + +## downloadRobotServerPlugin Task +Downloads `robot-server` plugin. +The `robot-server` plugin is required for running the UI tests using the [`runIdeForUiTests`](#runideforuitests-task) task. + + +### version +{id="downloadrobotserverplugin-task-version"} + +The version of the Robot Server Plugin to download. + +**Type:** `String` + +**Default value:** `LATEST` + + +### pluginArchive +{id="downloadrobotserverplugin-task-pluginarchive"} + +The archive with the Robot Server Plugin, downloaded by default to the [Gradle cache](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home). + +**Type:** `File` + +**Default value:** [Gradle cache](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home) + + +### outputDir +{id="downloadrobotserverplugin-task-outputdir"} + +Location of the extracted archive. + +**Type:** `File` + +**Default value:** `build/robotServerPlugin` + + +## instrumentCode Task +The following attributes help you to tune instrumenting behaviour in `instrumentCode { ... }` block. + + +### compilerVersion +{id="instrumentcode-task-compilerversion"} + +A version of instrumenting compiler. +It's used in cases when targeting non-IntelliJ IDEA IDEs (e.g. CLion or Rider). + +**Type:** `String` + +**Default value:** Build number of the IDE dependency + + +## jarSearchableOptions Task +Creates a JAR file with searchable options to be distributed with the plugin. + + +### outputDir +{id="jarsearchableoptions-task-outputdir"} + +The output directory where the JAR file will be created. + +**Type:** `String` + +Default value: `build/searchableOptions` + + +### pluginName +{id="jarsearchableoptions-task-pluginname"} + +The name of the plugin. + +**Type:** `String` + +Default value: [`intellij.pluginName`](#intellij-extension-pluginname) + + +### sandboxDir +{id="jarsearchableoptions-task-sandboxdir"} + +The sandbox output directory. + +**Type:** `String` + +Default value: [`prepareSandbox.outputDir`](#preparesandbox-task) + + +## listProductsReleases Task +List all available IntelliJ-based IDE releases with their updates. +The result list is used for testing the plugin with Plugin Verifier using the [`runPluginVerifier`](#runpluginverifier-task) task. + +Plugin Verifier requires a list of the IDEs that will be used for verifying your plugin build against. +The availability of the releases may change in time, i.e., due to security issues in one version – which will be later removed and replaced with an updated IDE release. + +With the [`listProductsReleases`](#listproductsreleases-task) task, it is possible to list the currently available IDEs matching given conditions, like platform types, since/until release versions. +Such a list is fetched from the remote updates file: `https://www.jetbrains.com/updates/updates.xml`, parsed and filtered considering the specified [`listProductsReleases.types`](#listproductsreleases-task-types), [`listProductsReleases.sinceVersion`](#listproductsreleases-task-sinceversion), [`listProductsReleases.untilVersion`](#listproductsreleases-task-untilversion) (or [`listProductsReleases.sinceBuild`](#listproductsreleases-task-sincebuild), [`listProductsReleases.untilBuild`](#listproductsreleases-task-untilbuild)) properties. + +The result list is stored within the [`listProductsReleases.outputFile`](#listproductsreleases-task-outputfile), which is used as a source for the Plugin Verifier if the [`runPluginVerifier`](#runpluginverifier-task) task has no [`runPluginVerifier.ideVersions`](#runpluginverifier-task-ideversions) property specified, the output of the [`listProductsReleases`](#listproductsreleases-task) task is used. + + +### updatesFile +{id="listproductsreleases-task-updatesfile"} + +Path to the products releases update file. +By default, falls back to the Maven cache. + +**Type:** `List` + +**Default value:** _Maven cache_ + + +### types +{id="listproductsreleases-task-types"} + +List of types of IDEs that will be listed in results. + +**Type:** `String` + +**Default value:** [`intellij.type`](#intellij-extension-type) + + +### sinceVersion +{id="listproductsreleases-task-sinceversion"} + +Lower boundary of the listed results in product marketing version format, like `2020.2.1`. +Takes precedence over [`listProductsReleases.sinceBuild`](#listproductsreleases-task-sincebuild) property. + +**Type:** `String` + +**Default value:** [`intellij.version`](#intellij-extension-version) + + +### untilVersion +{id="listproductsreleases-task-untilversion"} + +Upper boundary of the listed results in product marketing version format, like `2020.2.1`. +Takes precedence over [`listProductsReleases.untilBuild`](#listproductsreleases-task-untilbuild) property. + +**Type:** `String` + +**Default value:** `null` + + +### sinceBuild +{id="listproductsreleases-task-sincebuild"} + +Lower boundary of the listed results in build number format, like `192`. + +**Type:** `String` + +**Default value:** [`intellij.version`](#intellij-extension-version) + + +### untilBuild +{id="listproductsreleases-task-untilbuild"} + +Upper boundary of the listed results in build number format, like `192`. + +**Type:** `String` + +**Default value:** `null` + + +### releaseChannels +{id="listproductsreleases-task-releasechannels"} + +Release channels that product updates will be filtered with. + +**Type:** `Channel` + +**Default value:** `EnumSet.allOf(ListProductsReleasesTask.Channel)` + + +### outputFile +{id="listproductsreleases-task-outputfile"} + +Path to the file, where the output list will be stored. + +**Type:** `File` + +**Default value:** `File("${project.buildDir}/listProductsReleases.txt")` + + +### androidStudioUpdatePath +{id="listproductsreleases-task-androidstudioupdatepath"} + +For [Android Studio releases](android_studio_releases_list.md), a separated storage for the updates is used. + +**Type:** `String` + +**Default value:** `https://raw.githubusercontent.com/JetBrains/intellij-sdk-docs/main/topics/_generated/android_studio_releases.xml` + + +## patchPluginXml Task +Patches [plugin.xml](plugin_configuration_file.md) files with values provided to the task. + +> To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin). +> +{type="tip"} + + +### destinationDir +{id="patchpluginxml-task-destinationdir"} + +The directory where the patched [plugin.xml](plugin_configuration_file.md) will be written. + +**Type:** `String` + +**Default value:** `${project.buildDir}/patchedPluginXmlFiles` + + +### pluginXmlFiles +{id="patchpluginxml-task-pluginxmlfiles"} + +The list of [plugin.xml](plugin_configuration_file.md) files to patch. + +**Type:** `List` + +**Default value:** auto-discovered from the project + + +### pluginDescription +{id="patchpluginxml-task-plugindescription"} + +The description of the plugin – will be set to the `` tag. + +**Type:** `String` + +**Default value:** `null` + + +### sinceBuild +{id="patchpluginxml-task-sincebuild"} + +The lower bound of the version range to be patched – will be set for the `since-build` attribute of the `` tag. + +**Type:** `String` + +**Default value:** [`intellij.version`](#intellij-extension-version) in `Branch.Build.Fix` format + + +### untilBuild +{id="patchpluginxml-task-untilbuild"} + +The upper bound of the version range to be patched – will be set for the `until-build` attribute of the `` tag. + +**Type:** `String` + +**Default value:** [`intellij.version`](#intellij-extension-version) in `Branch.Build.*` format + + +### version +{id="patchpluginxml-task-version"} + +The version of the plugin – will be set for the `` tag. + +**Type:** `String` + +**Default value:** `${project.version}` + + +### changeNotes +{id="patchpluginxml-task-changenotes"} + +The change notes of the plugin – will be set for the `` tag. + +**Type:** `String` + +**Default value:** `null` + + +### pluginId +{id="patchpluginxml-task-pluginid"} + +The ID of the plugin – will be set for the `` tag. + +**Type:** `String` + +**Default value:** `null` + + +## prepareSandbox Task +Prepares sandbox directory with installed plugin and its dependencies. + + +### pluginName +{id="preparesandbox-task-pluginname"} + +The name of the plugin. + +**Type:** `String` + +**Default value:** [`intellij.pluginName`](#intellij-extension-pluginname) + + +### configDir +{id="preparesandbox-task-configdir"} + +The directory with the plugin configuration. + +**Type:** `String` + +**Default value:** `${intellij.pluginName}/config` + + +### pluginJar +{id="preparesandbox-task-pluginjar"} + +The input plugin JAR file used to prepare the sandbox. + +**Type:** `File` + +**Default value:** `jar` task output + + +### librariesToIgnore +{id="preparesandbox-task-librariestoignore"} + +Libraries that will be ignored when preparing the sandbox. +By default, excludes all libraries that are a part of the [`setupDependenciesTask.idea`](#setupdependencies-task-idea) dependency. + +**Type:** `List` + +**Default value:** `org.jetbrains.intellij.tasks.SetupDependenciesTask.idea.get().jarFiles` + + +### pluginDependencies +{id="preparesandbox-task-plugindependencies"} + +List of dependencies of the current plugin. + +**Type:** `List` + +**Default value:** `org.jetbrains.intellij.IntelliJPluginExtension.getPluginDependenciesList` + + +## prepareTestingSandbox Task +Prepares sandbox directory with installed plugin and its dependencies for testing purposes. + +See [`prepareSandbox` Task](#preparesandbox-task). + + +## prepareUiTestingSandbox Task +Prepares sandbox directory with installed plugin and its dependencies for UI testing purposes. + +See [`prepareSandbox` Task](#preparesandbox-task). + + +## publishPlugin Task +Publishes plugin to the remote [JetBrains Marketplace](https://plugins.jetbrains.com) repository. + +The following attributes are a part of the Publishing DSL `publishPlugin { ... }` in which allows Gradle to upload plugin to [JetBrains Marketplace](https://plugins.jetbrains.com). +Note that you need to [upload the plugin](publishing_plugin.md) to the repository at least once manually (to specify options like the license, repository URL etc.) before uploads through Gradle can be used. + +See the instruction on [how to generate authentication token](https://plugins.jetbrains.com/docs/marketplace/plugin-upload.html). + +See [Publishing Plugins with Gradle](deployment.md) tutorial for step-by-step instructions. + + +### token +{id="publishplugin-task-token"} + +Authentication token. + +**Required** + +**Type:** `String` + +**Default value:** `null` + + +### channels +{id="publishplugin-task-channels"} + +List of channel names to upload plugin to. + +**Type:** `List` + +**Default value:** `["default"]` + + +### host +{id="publishplugin-task-host"} + +URL host of a plugin repository. + +**Type:** `String` + +**Default value:** [JetBrains Marketplace](https://plugins.jetbrains.com) + + +### distributionFile +{id="publishplugin-task-distributionfile"} + +ZIP file of plugin to upload. + +**Type:** `File` + +**Default value:** output of the [`buildPlugin`](#buildplugin-task) task + + +### toolboxEnterprise +{id="publishplugin-task-toolboxenterprise"} + +Specifies if the Toolbox Enterprise plugin repository service should be used. +This feature is still in the incubating phase and is not yet available for public use. + +**Type:** `Boolean` + +**Default value:** `false` + + +## runIde Task +Runs the IDE instance with the developed plugin installed. + +`RunIde` tasks extend the [`JavaExec`](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html) Gradle task – all properties available in the `JavaExec` as well as the following ones can be used to configure the `runIde` taks. + + +### ideDir +{id="runide-task-idedir"} + +The IDEA dependency sources path. +Configured automatically with the [`setupDependencies.idea`](#setupdependencies-task-idea) dependency. + +**Type:** `File` + +**Default value:** [`setupDependencies.idea`](#setupdependencies-task-idea) + + +### jbrVersion +{id="runide-task-jbrversion"} + +Custom JBR version to use for running the IDE. + +**Type:** `String` + +**Default value:** `null` + +**Accepted values:** +- `8u112b752.4` +- `8u202b1483.24` +- `11_0_2b159` + +> For more information about JBR versions and variants, see [Using a JetBrains Runtime for the Development Instance](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). +> +{type="note"} + +### jbrVariant +{id="runide-task-jbrvariant"} + +JetBrains Runtime variant to use when running the IDE with the plugin. + +**Type:** `String` + +**Default value:** `null` + + +### pluginsDir +{id="runide-task-pluginsdir"} + +Path to the `plugins` directory within the sandbox prepared with the [`prepareSandbox`](#preparesandbox-task) task. +Provided to the `idea.plugins.path` system property. + +**Type:** `Directory` + +**Default value:** [`prepareSandbox.destinationDir`](#preparesandbox-task) + + +### autoReloadPlugins +{id="runide-task-autoreloadplugins"} + +Enables auto-reload of dynamic plugins. +Dynamic plugins will be reloaded automatically when their JARs are modified. +This allows a much faster development cycle by avoiding a full restart of the development instance after code changes. +Enabled by default in 2020.2 and higher. + +See [Enabling Auto-Reload](ide_development_instance.md#enabling-auto-reload) for more details. + +**Type:** `Boolean` + +**Default value:** `true` + + +## runIdeForUiTests Task +Runs the IDE instance with the developed plugin and robot-server installed and ready for UI testing. + +See [intellij-ui-test-robot](https://github.com/JetBrains/intellij-ui-test-robot) project. + +See [`runIde`](#runide-task) task for more details. + + +## runIdePerformanceTest Task +Runs performance tests on the IDE with the developed plugin installed. + +`RunIdePerformanceTest` task extends the `RunIdeBase` task, all configuration attributes of `JavaExec` and [`RunIde`](#runide-task) task can be used in `RunIdePerformanceTest` as well. +See [`runIde`](#runide-task) task for more details. + +Currently, the task is under adaptation, more documentation will be added in the future. + +### testDataDir +{id="runideperformancetest-task-testdatadir"} + +Path to directory with test projects and `.ijperf` files. + +**Type:** `String` + +**Default value:** `null` + + +### artifactsDir +{id="runideperformancetest-task-artifactsdir"} + +Path to directory where performance test artifacts (IDE logs, snapshots, screenshots, etc.) will be stored. +If the directory doesn't exist, it will be created. + +**Type:** `String` + +**Default value:** `null` + + +### profilerName +{id="runideperformancetest-task-profilername"} + +Name of the profiler which will be used during execution. + +**Type:** `ProfilerName` + +**Default value:** `ProfilerName.ASYNC` + +**Acceptable values:** +- `ProfilerName.ASYNC` +- `ProfilerName.YOURKIT` + + +## runPluginVerifier Task +Runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified [IDE builds](api_changes_list.md). + +Plugin Verifier DSL `runPluginVerifier { ... }` allows to define the list of IDEs used for the verification, as well as explicit tool version and any of the available [options](https://github.com/JetBrains/intellij-plugin-verifier#common-options) by proxifying them to the Verifier CLI. + +> For more details, examples or issues reporting, go to the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) repository. +> +{type="tip"} + +> To run Plugin Verifier in [`-offline`](https://github.com/JetBrains/intellij-plugin-verifier/pull/58) mode, set the Gradle [`offline` start parameter](https://docs.gradle.org/current/javadoc/org/gradle/StartParameter.html#setOffline-boolean-). +> +{type="tip"} + + +### ideVersions +{id="runpluginverifier-task-ideversions"} + +IDEs to check, in [`intellij.version`](#intellij-extension-version) format, i.e.: `["IC-2019.3.5", "PS-2019.3.2"]`. +Check the available build versions on [IntelliJ Platform Builds list](https://jb.gg/intellij-platform-builds-list). + +**Type:** `List` + +**Default value:** output of the [`listProductsReleases`](#listproductsreleases-task) task + + +### verifierVersion +{id="runpluginverifier-task-verifierversion"} + +IntelliJ Plugin Verifier version, by default uses the latest available. +Do not change unless absolutely required. + +**Type:** `String` + +**Default value:** `latest` + + +### verifierPath +{id="runpluginverifier-task-verifierpath"} + +IntelliJ Plugin Verifier local path to the pre-downloaded JAR file. +If set, [`runPluginVerifier.verifierVersion`](#runpluginverifier-task-verifierversion) is ignored. + +**Type:** `String` + +**Default value:** path to the JAR file resolved using the [`runPluginVerifier.verifierVersion`](#runpluginverifier-task-verifierversion) property + + +### localPaths +{id="runpluginverifier-task-localpaths"} + +A list of the paths to locally installed IDE distributions that should be used for verification in addition to those specified in [`runPluginVerifier.ideVersions`](#runpluginverifier-task-ideversions). + +**Type:** `List` + +**Default value:** `[]` + + +### distributionFile +{id="runpluginverifier-task-distributionfile"} + +ZIP file of the plugin to verify. +If empty, the task will be skipped. + +**Type:** `File` + +**Default value:** output of the `buildPlugin` task + + +### failureLevel +{id="runpluginverifier-task-failurelevel"} + +Defines the verification level at which task should fail if any reported issue will match. +Can be set as `FailureLevel` enum or `EnumSet`. + +**Type:** `FailureLevel` + +**Default value:** `FailureLevel.COMPATIBILITY_PROBLEMS` + +**Accepted values:** +- `FailureLevel.COMPATIBILITY_WARNINGS` - Compatibility warnings +- `FailureLevel.COMPATIBILITY_PROBLEMS` - Compatibility problems +- `FailureLevel.DEPRECATED_API_USAGES` - Deprecated API usages +- `FailureLevel.EXPERIMENTAL_API_USAGES` - Experimental API usages +- `FailureLevel.INTERNAL_API_USAGES` - Internal API usages +- `FailureLevel.OVERRIDE_ONLY_API_USAGES` - Override-only API usages +- `FailureLevel.NON_EXTENDABLE_API_USAGES` - Non-extendable API usages +- `FailureLevel.PLUGIN_STRUCTURE_WARNINGS` - Plugin structure warnings +- `FailureLevel.MISSING_DEPENDENCIES` - Missing dependencies +- `FailureLevel.INVALID_PLUGIN` - The following files specified for the verification are not valid plugins +- `FailureLevel.NOT_DYNAMIC` - Plugin cannot be loaded/unloaded without IDE restart +- `FailureLevel.ALL` - All of above +- `FailureLevel.NONE` - None of above + + +### verificationReportsDir +{id="runpluginverifier-task-verificationreportsdir"} + +The path to directory where verification reports will be saved. + +**Type:** `String` + +**Default value:** `${project.buildDir}/reports/pluginVerifier` + + +### downloadDir +{id="runpluginverifier-task-downloaddir"} + +The path to directory where IDEs used for the verification will be downloaded. + +**Type:** `String` + +**Default value:** `System.getProperty("plugin.verifier.home.dir")/ides` or `System.getProperty("user.home")/.pluginVerifier/ides` or system temporary directory. + + +### jbrVersion +{id="runpluginverifier-task-jbrversion"} + +Custom JBR version to use for running the IDE. + +**Type:** `String` + +**Default value:** `null` + +**Accepted values:** +- `8u112b752.4` +- `8u202b1483.24` +- `11_0_2b159` + +> For more information about JBR versions and variants, see [Using a JetBrains Runtime for the Development Instance](ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance). +> +{type="note"} + + +### jbrVariant +{id="runpluginverifier-task-jbrvariant"} + +JetBrains Runtime variant to use when running the IDE with the plugin. + +**Type:** `String` + +**Default value:** `null` + + +### runtimeDir +{id="runpluginverifier-task-runtimedir"} + +The path to directory containing JVM runtime, overrides [`runPluginVerifier.jbrVersion`](#runpluginverifier-task-jbrversion). + +**Type:** `String` + +**Default value:** `null` + + +### externalPrefixes +{id="runpluginverifier-task-externalprefixes"} + +The list of classes prefixes from the external libraries. +The Plugin Verifier will not report `No such class` for classes of these packages. + +**Type:** `List` + +**Default value:** `[]` + + +### teamCityOutputFormat +{id="runpluginverifier-task-teamcityoutputformat"} + +A flag that controls the output format - if set to `true`, the [TeamCity Tests Format](https://www.jetbrains.com/help/teamcity/service-messages.html) – the TeamCity compatible output will be returned to stdout. + +**Type:** `Boolean` + +**Default value:** `false` + + +### subsystemsToCheck +{id="runpluginverifier-task-subsystemstocheck"} + +Specifies which subsystems of IDE should be checked. + +**Type:** `String` + +**Default value:** `all` + +**Acceptable values:** +- `all` +- `android-only` +- `without-android` + + +## setupDependencies Task +Setups required dependencies for building and running project. + + +### idea +{id="setupdependencies-task-idea"} + +This task exposes the `setupDependencies.idea` property which contains a reference to the resolved IDE dependency used for building the plugin. + +This property can be referred in Gradle configuration to access IDE dependency classpath. + + +## signPlugin Task +Signs the ZIP archive with the provided key using [marketplace-zip-signer](https://github.com/JetBrains/marketplace-zip-signer) library. + +To sign the plugin before publishing to [JetBrains Marketplace](https://plugins.jetbrains.com) with the [`signPlugin`](#signplugin-task) task, it is required to provide a certificate chain and a private key with its password using `signPlugin { ... }` Plugin Signing DSL. + +As soon as [`signPlugin.privateKey`](#signplugin-task-privatekey) (or [`signPlugin.privateKeyFile`](#signplugin-task-privatekeyfile)) and [`signPlugin.certificateChain`](#signplugin-task-certificatechain) (or [`signPlugin.certificateChainFile`](#signplugin-task-certificatechainfile)) properties are specified, task will be executed automatically right before the [`publishPlugin`](#publishplugin-task) task. + +For more details, see [Plugin Signing](plugin_signing.md) article. + +### certificateChain +{id="signplugin-task-certificatechain"} + +A string containing X509 certificates. +The first certificate from the chain will be used as a certificate authority (CA). +Refers to `cert` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### certificateChainFile +{id="signplugin-task-certificatechainfile"} + +A file containing X509 certificates. +The first certificate from the chain will be used as a certificate authority (CA). +Refers to `cert-file` CLI option. + +**Type:** `File` + +**Default value:** `null` + + +### privateKey +{id="signplugin-task-privatekey"} + +Encoded private key in PEM format. +Refers to `key` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### privateKeyFile +{id="signplugin-task-privatekeyfile"} + +A file with encoded private key in PEM format. +Refers to `key-file` CLI option. + +**Type:** `File` + +**Default value:** `null` + + +### password +{id="signplugin-task-password"} + +Password required to decrypt the private key. +Refers to `key-pass` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### cliVersion +{id="signplugin-task-cliversion"} + +Returns the version of [JetBrains Marketplace ZIP Signer CLI](https://github.com/JetBrains/marketplace-zip-signer) that will be used. + +**Type:** `String` + +**Default value:** `LATEST` + + +### cliPath +{id="signplugin-task-clipath"} + +Path to [JetBrains Marketplace ZIP Signer CLI](https://github.com/JetBrains/marketplace-zip-signer) file. +Takes precedence over [`signPlugin.cliVersion`](#signplugin-task-cliversion). + +**Type:** `String` + +**Default value:** `null` + + +### keyStore +{id="signplugin-task-keystore"} + +KeyStore file path. +Refers to `ks` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### keyStorePassword +{id="signplugin-task-keystorepassword"} + +KeyStore password. + +**Type:** `String` + +**Default value:** `null` + + +### keyStoreKeyAlias +{id="signplugin-task-keystorekeyalias"} + +KeyStore key alias. +Refers to `ks-key-alias` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### keyStoreType +{id="signplugin-task-keystoretype"} + +KeyStore type. + +**Type:** `String` + +**Default value:** `null` + + +### keyStoreProviderName +{id="signplugin-task-keystoreprovidername"} + +JCA KeyStore Provider name. +Refers to `ks-provider-name` CLI option. + +**Type:** `String` + +**Default value:** `null` + + +### inputArchiveFile +{id="signplugin-task-inputarchivefile"} + +Input, unsigned ZIP archive file. +Refers to `in` CLI option. + +Provided by the [`buildPlugin`](#buildplugin-task) task. + +### outputArchiveFile +{id="signplugin-task-outputarchivefile"} + +Output, signed ZIP archive file. +Refers to `out` CLI option. + +Predefined with the name of the ZIP archive file with `-signed` name suffix attached. + +**Type:** `File` + + +## verifyPlugin Task +Validates completeness and contents of [plugin.xml](plugin_configuration_file.md) descriptors as well as plugin archive structure. + + +### ignoreFailures +{id="verifyplugin-task-ignorefailures"} + +Specifies whether the build should fail when the verifications performed by this task fail. + +**Type**: `Boolean` + +**Default value:** `false` + + +### ignoreWarnings +{id="verifyplugin-task-ignorewarnings"} + +Specifies whether the build should fail when the verifications performed by this task emit warnings. + +**Type**: `Boolean` + +**Default value:** `true` + + +### pluginDir +{id="verifyplugin-task-plugindir"} + +The location of the built plugin file which will be used for verification. + +**Type**: `File` + +**Default value:** `${prepareSandboxTask.destinationDir}/${prepareSandboxTask.pluginName}` + + + +## Build Features +With the Gradle IntelliJ Plugin releases, new features are introduced that require additional research, collecting more feedback from developers, or should be enabled or disabled under particular conditions. +Build Features are an implementation of the feature flags concept and let you control some behaviors of the Gradle IntelliJ Plugin. +To enable or disable a particular feature, add the Project property to the gradle.properties file, like: + +```properties +org.jetbrains.intellij.buildFeature.buildFeatureName=false +``` + +### selfUpdateCheck +{id="build-features-selfupdatecheck"} + +Check if the currently used Gradle IntelliJ Plugin is outdated. + +**Default value:** `true` diff --git a/topics/appendix/tools/tools_gradle_intellij_plugin_faq.md b/topics/appendix/tools/tools_gradle_intellij_plugin_faq.md new file mode 100644 index 000000000..5b8c35a19 --- /dev/null +++ b/topics/appendix/tools/tools_gradle_intellij_plugin_faq.md @@ -0,0 +1,146 @@ +[//]: # (title: Gradle IntelliJ Plugin – FAQ) + + + +## Frequently Asked Questions + +### How to modify JVM arguments of runIde task +[`runIde`](tools_gradle_intellij_plugin.md#runide-task) task is a [Java Exec](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html) task and can be modified according to the documentation. + +To add some JVM arguments while launching the IDE, configure [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task as follows: + + + + +```kotlin +tasks { + runIde { + jvmArgs("-DmyProperty=value") + } +} +``` + + + + +```groovy +runIde { + jvmArgs "-DmyProperty=value" +} +``` + + + + + +### How to modify system properties of runIde task +Using the [very same task documentation](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html), configure [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task: + + + + +```kotlin +tasks { + runIde { + systemProperty("name", "value") + } +} +``` + + + + +```groovy +runIde { + systemProperty("name", "value") +} +``` + + + + + +### How to disable automatic reload of dynamic plugins +Configure [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task as follows: + + + + +```kotlin +tasks { + runIde { + autoReloadPlugins.set(false) + } +} +``` + + + + +```groovy +runIde { + autoReloadPlugins = false +} +``` + + + + + +### How to disable building searchable options +Building searchable options can be disabled as a task: + + + + +```kotlin +tasks { + buildSearchableOptions { + enabled = false + } +} +``` + + + + +```groovy +buildSearchableOptions.enabled = false +``` + + + + +As a result of disabling building searchable options, the configurables that your plugin provides won't be searchable in the Settings dialog. + + +### How do I add my a custom file inside plugin distribution +[`prepareSandbox`](tools_gradle_intellij_plugin.md#preparesandbox-task) task is a [`Sync`](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.Sync.html) task and can be modified accordingly. +Something like following should work: + + + + +```kotlin +tasks { + prepareSandbox { + from("yourFile") { + into("${intellij.pluginName.get()}/lib/") + } + } +} +``` + + + + +```groovy +prepareSandbox { + from("yourFile") { + into "${intellij.pluginName.get()}/lib/" + } +} +``` + + + diff --git a/topics/basics/getting_started/build_number_ranges.md b/topics/basics/getting_started/build_number_ranges.md index a1f470b79..85df2c35b 100644 --- a/topics/basics/getting_started/build_number_ranges.md +++ b/topics/basics/getting_started/build_number_ranges.md @@ -3,7 +3,7 @@ Use this reference of build number ranges to specify the correct `since-build` and `until-build` values in your plugin descriptor. -Setting the actual values in plugin.xml is usually managed by `patchPluginXml` Gradle task, see [Patching the Plugin Configuration File](gradle_guide.md#patching-the-plugin-configuration-file) for details. +Setting the actual values in plugin.xml is usually managed by [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) Gradle task, see [Patching the Plugin Configuration File](gradle_guide.md#patching-the-plugin-configuration-file) for details. > Compatibility with the specified version range (and compatible products) must always be verified using [Plugin Verifier](api_changes_list.md#verifying-compatibility) to ensure binary compatibility. > @@ -12,7 +12,7 @@ Setting the actual values in plugin.xml is usually managed by `patc > {type="warning"} -Starting with IntelliJ IDEA 9 beta, a multi-part build number is used, such as `IU-162.94`. +Starting with IntelliJ IDEA 9 beta, a multipart build number is used, such as `IU-162.94`. The number consists of the following parts: diff --git a/topics/basics/getting_started/plugin_compatibility.md b/topics/basics/getting_started/plugin_compatibility.md index 25d2f8ec7..a9c4aeaea 100644 --- a/topics/basics/getting_started/plugin_compatibility.md +++ b/topics/basics/getting_started/plugin_compatibility.md @@ -235,7 +235,7 @@ If the project is not up-to-date, [reimport the Gradle project](https://www.jetb Reimporting the project will automatically update the dependencies. In the Project Window, select Project View and scroll to the bottom to see [External Libraries](https://www.jetbrains.com/help/idea/project-tool-window.html#content_pane). -Look for the library `Gradle:unzipped.com.jetbrains.plugins:foo:`, where "foo" matches, or is similar to the contents of the `` tags in plugin.xml or the `intellij.plugins` declaration in the Gradle build script. +Look for the library `Gradle:unzipped.com.jetbrains.plugins:foo:`, where "foo" matches, or is similar to the contents of the `` tags in plugin.xml or the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) declaration in the Gradle build script. The image below shows the External Libraries for the example plugin project configuration explained in [Configuring Gradle build script](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute) and [Configuring plugin.xml](dev_alternate_products.md#configuring-pluginxml). ![Example PhpStorm Project Libraries](php_prj_libs.png){width="700"} diff --git a/topics/basics/ide_development_instance.md b/topics/basics/ide_development_instance.md index ad75af288..48bf158fe 100644 --- a/topics/basics/ide_development_instance.md +++ b/topics/basics/ide_development_instance.md @@ -3,7 +3,7 @@ A JetBrains feature for developing plugins is running or debugging a plugin project from within an IntelliJ Platform-based IDE such as IntelliJ IDEA. -Selecting the [runIde](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task for a Gradle-based project (or [Run](running_and_debugging_a_plugin.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled. +Selecting the [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task for a Gradle-based project (or [Run](running_and_debugging_a_plugin.md) menu for a DevKit-based project) will launch a _Development Instance_ of the IDE with the plugin enabled. This page describes how to control some of the settings for the Development Instance. > Please see also [Advanced Configuration](https://www.jetbrains.com/help/idea/tuning-the-ide.html) for general VM options and properties. @@ -23,8 +23,8 @@ To produce accurate results while running or debugging a plugin project in a Dev The JetBrains Runtime is determined from the JDK version used to build the plugin project, regardless of whether it is built on macOS, Windows, or Linux. For example, if a plugin is developed against the Java 8 SE Development Kit 8 for macOS (jdk-8u212-macosx-x64.dmg) to acquire the compatible JetBrains Runtime: -* Go to the [JetBrains Runtime Site](https://confluence.jetbrains.com/display/JBR/JetBrains+Runtime) for general information and the latest build. -* Open the [Release notes](https://confluence.jetbrains.com/display/JBR/Release+notes) page to access all releases. +* Go to the [GitHub JetBrains Runtime Releases](https://github.com/JetBrains/JetBrainsRuntime) for general information and the latest build. +* Open the [Releases](https://github.com/JetBrains/JetBrainsRuntime/releases) page to access all releases. * Select the package name corresponding to the platform and SDK version. In this case, the package name is `jbrsdk8-osx-x64` for **J**et**B**rains **R**untime _SDK_ version 8, macOS x64 hardware. * On the macOS package page of the JetBrains Bintray site, select the **Files** menu. @@ -34,12 +34,27 @@ For example, if a plugin is developed against the Java 8 SE Development Kit 8 fo * Pick the highest JetBrains Runtime build number available. For example, the file is jbrx-8u252-osx-x64-b1649.2.tar.gz, meaning build 1649.2 for this JetBrains Runtime matching Java 8 JDK build 252. +### JetBrains Runtime Variants +The JetBrains Runtime is delivered in various variants used for different purposes, like debugging, running for development purposes or bundling with the IDE. + +Available JBR variants are: +- `jcef` - the release bundles with the [JCEF](jcef.md) browser engine +- `sdk` - JBR SDK bundle used for development purposes +- `fd` - the fastdebug bundle which also includes the `jcef` module +- `dcevm` - bundles DCEVM (Dynamic Code Evolution Virtual Machine) +- `nomod` – the release bundled without any additional modules + +> For `JBR 17`, `dcevm` is bundled by default. +> As a consequence, separated `dcevm` and `nomod` variants are no longer available. +> +{type="note"} + By default, the Gradle plugin will fetch and use the version of the JetBrains Runtime for the Development Instance corresponding to the version of the IntelliJ Platform used for building the plugin project. -If required, an alternative version can be specified using `jbrVersion` attribute of `runIde` [task](https://github.com/JetBrains/gradle-intellij-plugin/#running-dsl). +If required, an alternative version can be specified using [`runIde.jbrVersion`](tools_gradle_intellij_plugin.md#runide-task-jbrversion) task property. @@ -70,11 +85,11 @@ Please note that any unloading problems in a production environment will ask the Enabled by default for target platform 2020.2 or later. -Set `autoReloadPlugins = true` in [runIde](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task to enable it for earlier platform versions or `autoReloadPlugins = false` to disable it explicitly. +Set `intellij.autoReloadPlugins = true` in [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task to enable it for earlier platform versions or `intellij.autoReloadPlugins = false` to disable it explicitly. -After starting the sandbox IDE instance, run `buildPlugin` task after modifications in the plugin project and switch focus back to sandbox instance to trigger reload. +After starting the sandbox IDE instance, run [`buildPlugin`](tools_gradle_intellij_plugin.md#buildplugin-task) task after modifications in the plugin project and switch focus back to sandbox instance to trigger reload. -> `buildSearchableOptions` task must currently be [disabled explicitly](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/FAQ.md#how-to-disable-building-searchable-options) to workaround _Only one instance of IDEA can be run at a time_ problem. +> [`buildSearchableOptions`](tools_gradle_intellij_plugin.md#buildsearchableoptions-task) task must currently be [disabled explicitly](tools_gradle_intellij_plugin_faq.md#how-to-disable-building-searchable-options) to workaround _Only one instance of IDEA can be run at a time_ problem. > {type="warning"} @@ -97,7 +112,7 @@ This information is stored in a different location than for the [installed IDE i -For Gradle-based plugins, the default Sandbox Home location is defined by the IntelliJ Platform `gradle-intellij-plugin`. +For Gradle-based plugins, the default Sandbox Home location is defined by the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). See [Configuring a Gradle Plugin Project](gradle_prerequisites.md) for more information about specifying a Sandbox Home location. The default Sandbox Home location is: diff --git a/topics/basics/plugin_signing.md b/topics/basics/plugin_signing.md index f218b8cf6..639717445 100644 --- a/topics/basics/plugin_signing.md +++ b/topics/basics/plugin_signing.md @@ -38,7 +38,7 @@ JetBrains Marketplace uses AWS KMS as a signature provider to sign plugin files. ## Signing Methods To provide a suitable method for plugin signing, we have introduced the [Marketplace ZIP Signer](https://github.com/JetBrains/marketplace-zip-signer) library. -It can be executed using the `signPlugin` task provided by the [Gradle IntelliJ Plugin](https://github.com/JetBrains/gradle-intellij-plugin) if your project is Gradle-based. +It can be executed using the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task provided by the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) if your project is Gradle-based. Alternatively, it can be used standalone [CLI Tool](#cli-tool). Both methods require a private certificate key to be already present. @@ -55,8 +55,8 @@ openssl genpkey\ -pkeyopt rsa_keygen_bits:4096 ``` -At this point, the generated private.pem content should be provided to the `signPlugin.privateKey` property. -Provided password should be specified as the `signPlugin.password` property in the `signPlugin` configuration. +At this point, the generated private.pem content should be provided to the [`signPlugin.privateKey`](tools_gradle_intellij_plugin.md#signplugin-task-privatekey) property. +Provided password should be specified as the [`signPlugin.password`](tools_gradle_intellij_plugin.md#signplugin-task-password) property in the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) configuration. As a next step, we'll generate a chain.crt certificate chain with: @@ -69,14 +69,14 @@ openssl req\ -out chain.crt ``` -The content of the chain.crt file will be used for the `signPlugin.certificateChain` property. +The content of the chain.crt file will be used for the [`signPlugin.certificateChain`](tools_gradle_intellij_plugin.md#signplugin-task-certificatechain) property. ### Gradle IntelliJ Plugin -In version `1.x`, the Gradle IntelliJ Plugin provides the `signPlugin` task, which will be executed automatically right before the `publishPlugin` task when `signPlugin certificateChain` and `signPlugin.privateKey` signing properties are specified. +In version `1.x`, the Gradle IntelliJ Plugin provides the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task, which will be executed automatically right before the [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) task when [`signPlugin.certificateChain`](tools_gradle_intellij_plugin.md#signplugin-task-certificatechain) and [`signPlugin.privateKey`](tools_gradle_intellij_plugin.md#signplugin-task-privatekey) signing properties are specified. Otherwise, it'll be skipped. -An example `pluginSigning` configuration may look like: +An example [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task configuration may look like: @@ -150,7 +150,7 @@ publishPlugin { To avoid storing hard-coded values in the project configuration, the most suitable method for local development would be using environment variables provided within the _Run/Debug Configuration_. -To specify secrets like `PUBLISH_TOKEN` and values required for the `signPlugin` task, modify your Gradle configuration as follows: +To specify secrets like `PUBLISH_TOKEN` and values required for the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task, modify your Gradle configuration as follows: @@ -185,7 +185,7 @@ publishPlugin { -In the Run/Debug Configuration for `publishPlugin` Gradle task, provide Environment Variables using relevant environment variable names: +In the Run/Debug Configuration for [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) Gradle task, provide Environment Variables using relevant environment variable names: ![Run/Debug Configuration Environment Variables](plugin_singing_env_variables.png) diff --git a/topics/basics/plugin_structure/plugin_dependencies.md b/topics/basics/plugin_structure/plugin_dependencies.md index 41b43d3b6..43c52d141 100644 --- a/topics/basics/plugin_structure/plugin_dependencies.md +++ b/topics/basics/plugin_structure/plugin_dependencies.md @@ -67,11 +67,11 @@ Depending on the chosen development workflow (Gradle or DevKit), one of the two -> Please see the `plugins` attribute [gradle-intellij-plugin: Configuration](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for acceptable values. +> Please see the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) property for acceptable values. > {type="note"} -If the project uses [Gradle](gradle_build_system.md), add the dependency to the `plugins` parameter of the `intellij` block in your build script: +If the project uses [Gradle](gradle_build_system.md), add the dependency to the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) parameter in your build script: diff --git a/topics/basics/testing_plugins/testing_plugins.md b/topics/basics/testing_plugins/testing_plugins.md index 96dd6e8ad..8e420473f 100644 --- a/topics/basics/testing_plugins/testing_plugins.md +++ b/topics/basics/testing_plugins/testing_plugins.md @@ -26,7 +26,7 @@ See also [](testing_faq.md#how-to-replace-componentservice-in-tests) and [](test ### UI Tests Please see the dedicated [intellij-ui-test-robot](https://github.com/JetBrains/intellij-ui-test-robot) library. -It is fully integrated with Gradle-based setup via `runIdeForUiTests` task. +It is fully integrated with Gradle-based setup via [`runIdeForUiTests`](tools_gradle_intellij_plugin.md#runideforuitests-task) task. Please do not use platform/testGuiFramework it is reserved for internal use. diff --git a/topics/intro/code_samples.md b/topics/intro/code_samples.md index 7632eebab..a30a83af7 100644 --- a/topics/intro/code_samples.md +++ b/topics/intro/code_samples.md @@ -34,4 +34,4 @@ Invoke Reload All Gradle Projects from the Gradle tool window ## Running Code Samples -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#executing-the-plugin) shown under the corresponding project's Tasks node in the Gradle tool window. +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#executing-the-plugin) task shown under the corresponding project's Tasks node in the Gradle tool window. diff --git a/topics/intro/content_updates.md b/topics/intro/content_updates.md index 4d7e27231..27ab9c162 100644 --- a/topics/intro/content_updates.md +++ b/topics/intro/content_updates.md @@ -83,7 +83,7 @@ Extension Point Lists: Listeners, Deprecation status ### July-21 Plugin Signing -: [](plugin_signing.md) describes the plugin signing process, explains how to generate a certificate, configure the Gradle `signPlugin` task, and introduces a standalone CLI tool. +: [](plugin_signing.md) describes the plugin signing process, explains how to generate a certificate, configure the Gradle [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task, and introduces a standalone CLI tool. ### June-21 diff --git a/topics/intro/sdk_code_guidelines.md b/topics/intro/sdk_code_guidelines.md index 11e26abb5..ba1f00cae 100644 --- a/topics/intro/sdk_code_guidelines.md +++ b/topics/intro/sdk_code_guidelines.md @@ -139,7 +139,7 @@ Comments in SDK code sample Gradle build scripts should only draw attention to t For SDK code samples, a few alterations are needed to the default build.gradle.kts file produced by the plugin wizard: * Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`). See the [Plugin Gradle Properties](gradle_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 statement to the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin#patching-dsl) (`patchPluginXml {...}`) section: +* Add the following statement to the [Patching DSL](tools_gradle_intellij_plugin.md#patchpluginxml-task) (`patchPluginXml {...}`) section: ```kotlin // Patches value in plugin.xml version.set(project.version) diff --git a/topics/products/androidstudio/android_studio.md b/topics/products/androidstudio/android_studio.md index e890241ee..ff987aeeb 100644 --- a/topics/products/androidstudio/android_studio.md +++ b/topics/products/androidstudio/android_studio.md @@ -28,7 +28,7 @@ To find the version of the IntelliJ Platform used to build Android Studio, use t An example is shown below. In this case, the (BRANCH.BUILD.FIX) version of the IntelliJ Platform is `211.7628.21` – marked with the blue rectangle – is corresponding to the IntelliJ IDEA version `2021.1.3`. -In your Gradle build script, you should set both versions – build number and the release number – to the `intellij.version` property. +In your Gradle build script, you should set both versions – build number and the release number – to the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) property. To figure out the exact release number based on the build number, visit the [IntelliJ Repository Releases](https://www.jetbrains.com/intellij-repository/releases/) listing and check the `com.jetbrains.intellij.idea` section. The [Gradle build script configuration steps](#configuring-the-plugin-gradle-build-script) section below explains how to set the IntelliJ Platform version to match the target version of Android Studio. @@ -49,11 +49,11 @@ The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugi The particular example in that section discusses configuring a plugin project for PhpStorm, so the details for an Android Studio plugin project are reviewed here. Here are the steps to configure the Gradle build script for developing a plugin to target Android Studio: -* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set. - Continuing with the example [above](#matching-versions-of-the-intellij-platform-with-the-android-studio-version), set the `intellij.version` value to `191.8026.42`. - Alternatively, specify `intellij.localPath` to refer to a local installation of Android Studio. +* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set. + Continuing with the example [above](#matching-versions-of-the-intellij-platform-with-the-android-studio-version), set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) value to `191.8026.42`. + Alternatively, specify [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) to refer to a local installation of Android Studio. * Android Studio plugin projects that use APIs from the `android` plugin must declare a dependency on that plugin. - Declare the dependency in the Gradle build script using the `intellij.plugins` attribute, which in this case lists the [directory name](https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties) of the plugin. + Declare the dependency in the Gradle build script using the [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) attribute, which in this case lists the [directory name](tools_gradle_intellij_plugin.md#intellij-extension-pluginname) of the plugin. * The best practice is to use the target version of Android Studio as the IDE Development Instance. Set the Development Instance to the (user-specific) absolute path to the target Android Studio application. diff --git a/topics/products/appcode/app_code.md b/topics/products/appcode/app_code.md index 422f967f4..92a39a413 100644 --- a/topics/products/appcode/app_code.md +++ b/topics/products/appcode/app_code.md @@ -2,7 +2,7 @@ -Plugin projects targeting [AppCode](https://www.jetbrains.com/objc/) can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects targeting [AppCode](https://www.jetbrains.com/objc/) can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -15,22 +15,19 @@ Plugin projects targeting [AppCode](https://www.jetbrains.com/objc/) can be deve {type="warning"} The Gradle configuration of AppCode plugin projects uses neither Product-Specific nor IntelliJ IDEA Attributes. -Instead, configure AppCode plugin projects to use the `intellij.localPath` attribute. +Instead, configure AppCode plugin projects to use the [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) attribute. > AppCode plugin development requires installing AppCode locally. > {type="note"} -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.localPath`][properties] | Path to locally installed target version of AppCode. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of AppCode. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) | Path to locally installed target version of AppCode. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of AppCode. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/AppCode/ch-0/193.5662.55/AppCode.app/Contents. | The dependency on the AppCode APIs must be declared in the plugin.xml file. As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.appcode` module dependency, or `com.intellij.appcode` plugin dependency for plugins targeting only versions 2020.3+. diff --git a/topics/products/clion/clion.md b/topics/products/clion/clion.md index f3ebb2551..4d9c98879 100644 --- a/topics/products/clion/clion.md +++ b/topics/products/clion/clion.md @@ -3,7 +3,7 @@ [CLion](https://www.jetbrains.com/clion/) is an IntelliJ Platform-based product. -Plugin projects for CLion can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects for CLion can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -17,19 +17,16 @@ Plugin projects for CLion can be developed using IntelliJ IDEA with the `gradle- The configuration of CLion plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------------|--------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `CL` for the product CLion. | -| [`intellij.version`][properties] | Set to the targeted CLion version, e.g. `2019.3.1`. | -| [`intellij.plugins`][properties] | No specific declaration is needed. | -| [`intellij.downloadSources`][properties] | `false` is required because no public source code is available. | -| [`runIde.ideDir`][dsl] | Not needed; the Development Instance will automatically match `intellij.type`. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `CL` for the product CLion. | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | Set to the targeted CLion version, e.g. `2019.3.1`. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | No specific declaration is needed. | +| [`intellij.downloadSources`](tools_gradle_intellij_plugin.md#intellij-extension-downloadsources) | `false` is required because no public source code is available. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Not needed; the Development Instance will automatically match `intellij.type`. | The dependency on the CLion APIs must be declared in the plugin.xml file. As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.modules.clion` module dependency, or `com.intellij.clion` plugin dependency for plugins targeting only versions 2020.3+. diff --git a/topics/products/datagrip/data_grip.md b/topics/products/datagrip/data_grip.md index d247acc12..e1d4334ec 100644 --- a/topics/products/datagrip/data_grip.md +++ b/topics/products/datagrip/data_grip.md @@ -3,7 +3,7 @@ [DataGrip](https://www.jetbrains.com/datagrip/) is an IntelliJ Platform-based product. -Plugin projects targeting DataGrip can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects targeting DataGrip can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -12,19 +12,16 @@ Plugin projects targeting DataGrip can be developed using IntelliJ IDEA with the ## Configuring Plugin Projects Targeting DataGrip The configuration of DataGrip plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. To see how these attributes appear in a similar Gradle build script for PhpStorm, see [](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `DatabaseTools` plugin.) | -| [`intellij.version`][properties] | `2019.3` Set to the same version as the DataGrip target version, as set by `runIde.ideDir`. | -| [`intellij.plugins`][properties] | `DatabaseTools` Dependency on the bundled `DatabaseTools` plugin. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of DataGrip. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/datagrip/ch-0/193.5233.139/DataGrip.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `DatabaseTools` plugin.) | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | `2019.3` Set to the same version as the DataGrip target version, as set by `runIde.ideDir`. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | `DatabaseTools` Dependency on the bundled `DatabaseTools` plugin. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of DataGrip. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/datagrip/ch-0/193.5233.139/DataGrip.app/Contents. | The dependency on the DataGrip APIs must be declared in the plugin.xml file. As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `com.intellij.database`. diff --git a/topics/products/dev_alternate_products.md b/topics/products/dev_alternate_products.md index ef009accc..34b1acad5 100644 --- a/topics/products/dev_alternate_products.md +++ b/topics/products/dev_alternate_products.md @@ -10,7 +10,7 @@ Once completed, the plugins can be packaged and distributed at [JetBrains Market Project configuration attributes common to projects targeting products other than IntelliJ IDEA are described on this page. Details particular to an IntelliJ Platform-based product are described on the individual product pages in _Part VIII — Product Specific_. -All the Gradle configuration attributes described here are discussed in-depth on the [](gradle_guide.md) and the `gradle-intellij-plugin` [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) pages. +All the Gradle configuration attributes described here are discussed in-depth on the [](gradle_guide.md) and the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -27,11 +27,11 @@ The plugin.xml file is modified to declare the plugin's dependency ## Configuring Gradle Build Script to Target Products Other Than IntelliJ IDEA -The best practice is to use the `gradle-intellij-plugin` `intellij.type` [attribute](https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties) to specify the target product. +The best practice is to use the [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property to specify the target product. For example, `PY` for PyCharm Professional. -Configuration using an `intellij.type` attribute is explained in the [Product-Specific Attribute](#configuring-plugin-projects-using-a-product-specific-attribute) section below. +Configuration using an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property is explained in the [Product-Specific Attribute](#configuring-plugin-projects-using-a-product-specific-attribute) section below. -NOTE: Not all products have an `intellij.type` attribute defined by the `gradle-intellij-plugin`, for example, [Android Studio](android_studio.md) and [PhpStorm](phpstorm.md). +NOTE: Not all products have an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property defined by the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md), for example, [Android Studio](android_studio.md) and [PhpStorm](phpstorm.md). The best approach then is to configure the project using the [IntelliJ IDEA Attribute](#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). > To target multiple products (e.g., IntelliJ IDEA and PyCharm) with the same plugin, see [](plugin_compatibility.md) page. @@ -40,14 +40,14 @@ The best approach then is to configure the project using the [IntelliJ IDEA Attr ### Configuring Plugin Projects Using a Product-Specific Attribute -If the `gradle-intellij-plugin` supports a target product directly, there will be an `intellij.type` [attribute](https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties) defined. -Specifying the target as a product-specific `intellij.type` attribute has two advantages: +If the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) supports a target product directly, there will be an [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property defined. +Specifying the target as a product-specific [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) property has two advantages: * The APIs available to the plugin will be limited to only what is defined in the target product. (Unless additional plugin dependencies are specified.) * The default [Development Instance](ide_development_instance.md) for running the plugin will be the target product. A Gradle build script snippet setting a plugin project to target PyCharm is shown below. -The `gradle-intellij-plugin` will fetch the matching build of PyCharm Professional to define the APIs available, and use that build of PyCharm (and associated JetBrains runtime) as the Development Instance. +The [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) will fetch the matching build of PyCharm Professional to define the APIs available, and use that build of PyCharm (and associated JetBrains Runtime) as the Development Instance. No additional product-specific configuration needs to be set in the Gradle build script: @@ -75,7 +75,7 @@ intellij { ### Configuring Plugin Projects Using the IntelliJ IDEA Product Attribute -If the `gradle-intellij-plugin` does not directly support an IntelliJ Platform-based product, the Gradle build script can still be configured to target the desired product. +If the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) does not directly support an IntelliJ Platform-based product, the Gradle build script can still be configured to target the desired product. In this case, the build script is configured to use IntelliJ IDEA (Community or Ultimate Edition) as the basis for the available APIs. This does have the drawback that APIs not specific to the target product might accidentally be included in the plugin project. However, testing the plugin project in the target product itself helps to find such mistakes. @@ -116,18 +116,18 @@ This information is used to configure the plugin project's Gradle build script a #### Configuring Gradle Build Script Using the IntelliJ IDEA Product Attribute Configuring a Gradle plugin project for using _baseIntelliJPlatformVersion_ requires changing some default settings in the Gradle build script. -Changes need to be made in two tasks: `intellij` and `runIde`. +Changes need to be made in two places: [`intellij`](tools_gradle_intellij_plugin.md#intellij-extension) extension and [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task. -The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set in the `intellij` task. -The `intellij.type` is `IU` because although the IntelliJ IDEA Community Edition defines the IntelliJ Platform, the PHP plugin is only compatible with IntelliJ IDEA Ultimate. -The `intellij.version` is _baseIntelliJPlatformVersion_. +The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](gradle_guide.md#configuring-the-gradle-intellij-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set in the `intellij` task. +The [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) is `IU` because although the IntelliJ IDEA Community Edition defines the IntelliJ Platform, the PHP plugin is only compatible with IntelliJ IDEA Ultimate. +The [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) is _baseIntelliJPlatformVersion_. -Any [dependencies](gradle_guide.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the `intellij` task. -Use the Gradle plugin attribute `intellij.plugins` to declare a dependency. +Any [dependencies](gradle_guide.md#plugin-dependencies) on _targetIDE_-specific plugins or modules must be declared in the [`intellij`](tools_gradle_intellij_plugin.md#intellij-extension) extension. +Use the Gradle plugin attribute [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) to declare a dependency. See the specific product pages in _Part VIII — Product Specific_ for the _targetIDE_ plugin or module name. -The best practice is to modify the `runIde` task to use a local installation of _targetIDE_ as the [](ide_development_instance.md). -Set the `runIde.ideDir` attribute to the (user-specific) absolute path of the _targetIDE_ application. +The best practice is to modify the [`runIde`](tools_gradle_intellij_plugin.md#runide-task) task to use a local installation of _targetIDE_ as the [](ide_development_instance.md). +Set the [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) attribute to the (user-specific) absolute path of the _targetIDE_ application. The exact path format varies by operating system. This snippet is an example for configuring the Setup and Running DSLs in a Gradle build script specific to developing a plugin for _targetIDE_. diff --git a/topics/products/goland/goland.md b/topics/products/goland/goland.md index 3bc51f875..9e98bf4dc 100644 --- a/topics/products/goland/goland.md +++ b/topics/products/goland/goland.md @@ -3,7 +3,7 @@ [GoLand](https://www.jetbrains.com/go/) is an IntelliJ Platform-based product. -Plugin projects for GoLand can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects for GoLand can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -49,22 +49,19 @@ intellij { The configuration of GoLand plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. To see how these attributes appear in a similar Gradle build script for PhpStorm, see [](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). The Go plugin version is explicitly declared because it isn't bundled with IntelliJ IDEA Ultimate Edition. Select a [version](https://plugins.jetbrains.com/plugin/9568-go/versions) of the Go plugin compatible with the IntelliJ Idea Ultimate version. -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. The Go plugin isn't compatible with IntelliJ IDEA Community Edition. | -| [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the GoLand target version, e.g. `193.5233.102`. | -| [`intellij.plugins`][properties] | `org.jetbrains.plugins.go:193.5233.102.83` for the Go plugin.
See below for Go plugin version information. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of GoLand. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/Goland/ch-0/193.5233.112/GoLand.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `IU` for IntelliJ IDEA Ultimate. The Go plugin isn't compatible with IntelliJ IDEA Community Edition. | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | Set to the same `IU` BRANCH.BUILD as the GoLand target version, e.g. `193.5233.102`. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | `org.jetbrains.plugins.go:193.5233.102.83` for the Go plugin.
See below for Go plugin version information. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of GoLand. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/Goland/ch-0/193.5233.112/GoLand.app/Contents. | diff --git a/topics/products/phpstorm/phpstorm.md b/topics/products/phpstorm/phpstorm.md index ea8da787a..d738fd9b4 100644 --- a/topics/products/phpstorm/phpstorm.md +++ b/topics/products/phpstorm/phpstorm.md @@ -24,21 +24,18 @@ The recommended best practice is to use PhpStorm for testing. Configuration of a Gradle-based PhpStorm plugin project is used as a tutorial in the section [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute). Many techniques are discussed, such as choosing a version of IntelliJ IDEA Ultimate given a targeted version of PhpStorm. -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. To see how these attributes appear in the Gradle build script for PhpStorm, see [](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. The required PHP plugin isn't compatible with IntelliJ IDEA Community Edition. | -| [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the PhpStorm target version, e.g. `193.5233.102`. | -| [`intellij.plugins`][properties] | `com.jetbrains.php:193.5233.102` for the PHP plugin.
See below for PHP plugin version information. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of PhpStorm. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/193.5233.101/PhpStorm.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `IU` for IntelliJ IDEA Ultimate. The required PHP plugin isn't compatible with IntelliJ IDEA Community Edition. | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | Set to the same `IU` BRANCH.BUILD as the PhpStorm target version, e.g. `193.5233.102`. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | `com.jetbrains.php:193.5233.102` for the PHP plugin.
See below for PHP plugin version information. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of PhpStorm. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/193.5233.101/PhpStorm.app/Contents. | The PHP plugin version is explicitly declared because it isn't bundled with IntelliJ IDEA Ultimate Edition. -Select a [version](https://plugins.jetbrains.com/plugin/6610-php/versions) of the PHP plugin compatible with the `intellij.version`. +Select a [version](https://plugins.jetbrains.com/plugin/6610-php/versions) of the PHP plugin compatible with the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version). The dependency on the PHP plugin APIs must be declared in the plugin.xml file, as shown in the tutorial [Configuring plugin.xml](dev_alternate_products.md#configuring-pluginxml) section. diff --git a/topics/products/pycharm/pycharm.md b/topics/products/pycharm/pycharm.md index 7bb2e13d5..304ab3840 100644 --- a/topics/products/pycharm/pycharm.md +++ b/topics/products/pycharm/pycharm.md @@ -3,7 +3,7 @@ [PyCharm](https://www.jetbrains.com/pycharm/) is an IntelliJ Platform-based product. -Plugin projects for PyCharm can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects for PyCharm can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -11,19 +11,16 @@ Plugin projects for PyCharm can be developed using IntelliJ IDEA with the `gradl ## Configuring Plugin Projects Targeting PyCharm The configuration of PyCharm plugin projects follows the methods described in [Configuring Plugin Projects using a Product-Specific Attribute](dev_alternate_products.md#configuring-plugin-projects-using-a-product-specific-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -The table below summarizes the `gradle-intellij-plugin` attributes to set in the Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------------|--------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `PY` for PyCharm Professional Edition, or `PC` for PyCharm Community Edition. | -| [`intellij.version`][properties] | Set to the targeted `PY` or `PC` version. | -| [`intellij.plugins`][properties] | `Pythonid` for `PY` / `PythonCore` for `PC`. | -| [`intellij.downloadSources`][properties] | `false` is required because no public source code is available. | -| [`runIde.ideDir`][dsl] | Not needed; the Development Instance will automatically match `intellij.type`. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `PY` for PyCharm Professional Edition, or `PC` for PyCharm Community Edition. | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | Set to the targeted `PY` or `PC` version. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | `Pythonid` for `PY` / `PythonCore` for `PC`. | +| [`intellij.downloadSources`](tools_gradle_intellij_plugin.md#intellij-extension-downloadsources) | `false` is required because no public source code is available. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Not needed; the Development Instance will automatically match `intellij.type`. | The dependency on the PyCharm APIs must be declared in the plugin.xml file. As described in [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml), the `` tags must declare `com.intellij.modules.python`. diff --git a/topics/products/rubymine/rubymine.md b/topics/products/rubymine/rubymine.md index 52f914759..ae299161a 100644 --- a/topics/products/rubymine/rubymine.md +++ b/topics/products/rubymine/rubymine.md @@ -3,7 +3,7 @@ [RubyMine](https://www.jetbrains.com/ruby/) is an IntelliJ Platform-based product. -Plugin projects for RubyMine can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects for RubyMine can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Qualifying Open Source projects can [apply for free licenses](https://www.jetbrains.com/community/opensource/) of JetBrains products. > @@ -13,19 +13,16 @@ Plugin projects for RubyMine can be developed using IntelliJ IDEA with the `grad The configuration of RubyMine plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute), and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml). -The table below summarizes the `gradle-intellij-plugin` attributes to set in the Gradle build script for a RubyMine plugin project. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the Gradle build script for a RubyMine plugin project. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. To see how these attributes appear in a similar Gradle build script for PhpStorm, see [](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate. | -| [`intellij.version`][properties] | Set to the same `IU` BRANCH.BUILD as the RubyMine target version, e.g. `192.7142.36`. | -| [`intellij.plugins`][properties] | `org.jetbrains.plugins.ruby:2019.2.20191029` for the Ruby plugin.
See below for Ruby plugin version information. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of RubyMine. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/RubyMine/ch-0/192.7142.37/RubyMine.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `IU` for IntelliJ IDEA Ultimate. | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | Set to the same `IU` BRANCH.BUILD as the RubyMine target version, e.g. `192.7142.36`. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | `org.jetbrains.plugins.ruby:2019.2.20191029` for the Ruby plugin.
See below for Ruby plugin version information. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of RubyMine. For example, on macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/RubyMine/ch-0/192.7142.37/RubyMine.app/Contents. | The required `org.jetbrains.plugins.ruby` plugin isn't compatible with IntelliJ IDEA Community edition but is compatible with IntelliJ IDEA Ultimate (`IU`) edition. Product compatibility is determined from the Ruby plugin [version page](https://plugins.jetbrains.com/plugin/1293-ruby/versions). diff --git a/topics/products/webstorm/webstorm.md b/topics/products/webstorm/webstorm.md index b37207c44..82a664985 100644 --- a/topics/products/webstorm/webstorm.md +++ b/topics/products/webstorm/webstorm.md @@ -3,7 +3,7 @@ [WebStorm](https://www.jetbrains.com/webstorm/) is an IntelliJ Platform-based product. -Plugin projects for WebStorm can be developed using IntelliJ IDEA with the `gradle-intellij-plugin`. +Plugin projects for WebStorm can be developed using IntelliJ IDEA with the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). > Follow [Building a Plugin for WebStorm – Tutorial for JavaScript Developers](learning_resources.md#articles) blog post series to get started. > @@ -16,19 +16,16 @@ Plugin projects for WebStorm can be developed using IntelliJ IDEA with the `grad ## Configuring Plugin Projects Targeting WebStorm The configuration of WebStorm plugin projects follows the methods described in [Configuring Plugin Projects using the IntelliJ IDEA Product Attribute](dev_alternate_products.md#configuring-plugin-projects-using-the-intellij-idea-product-attribute) and [Configuring the plugin.xml File](dev_alternate_products.md#configuring-pluginxml) for PhpStorm. -The table below summarizes the `gradle-intellij-plugin` attributes to set in the plugin project's Gradle build script. +The table below summarizes the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) attributes to set in the plugin project's Gradle build script. Click on an entry in the table's *Attribute* column to go to the documentation about that attribute. To see how these attributes appear in a similar Gradle build script for PhpStorm, see [](dev_alternate_products.md#configuring-gradle-build-script-using-the-intellij-idea-product-attribute). -| `gradle-intellij-plugin` Attribute | Attribute Value | -|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`intellij.type`][properties] | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `JavaScriptLanguage` plugin) | -| [`intellij.version`][properties] | `192.7142.36` Set to the same BRANCH.BUILD as the WebStorm target version. | -| [`intellij.plugins`][properties] | Dependency on the `JavaScriptLanguage` plugin. | -| [`runIde.ideDir`][dsl] | Path to locally installed target version of WebStorm. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/WebStorm/ch-0/192.7142.35/WebStorm.app/Contents. | - -[properties]: https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties -[dsl]: https://github.com/JetBrains/gradle-intellij-plugin#running-dsl +| `gradle-intellij-plugin` Attribute | Attribute Value | +|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) | `IU` for IntelliJ IDEA Ultimate.
(`IC` is incompatible with the required `JavaScriptLanguage` plugin) | +| [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) | `192.7142.36` Set to the same BRANCH.BUILD as the WebStorm target version. | +| [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins) | Dependency on the `JavaScriptLanguage` plugin. | +| [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) | Path to locally installed target version of WebStorm. For example, for macOS:
/Users/$USERNAME$/Library/Application Support/JetBrains/Toolbox/apps/WebStorm/ch-0/192.7142.35/WebStorm.app/Contents. | The dependency on the WebStorm APIs must be declared in the plugin.xml file. As described in [Modules Specific to Functionality](plugin_compatibility.md#modules-specific-to-functionality) table, the `` tags must declare `JavaScriptLanguage`. diff --git a/topics/reference_guide/intellij_artifacts.md b/topics/reference_guide/intellij_artifacts.md index 3d150b7c7..84d4db187 100644 --- a/topics/reference_guide/intellij_artifacts.md +++ b/topics/reference_guide/intellij_artifacts.md @@ -18,7 +18,7 @@ See the [Maven coordinates](#specify-the-maven-coordinates-for-the-artifact) sec Both the Releases and Snapshots repositories have two types of content: * Binary and source code artifacts for cross-platform, ZIP distributions of IntelliJ Platform-based IDEs, such as IntelliJ IDEA, CLion, Rider, and MPS. These artifacts are _not intended_ to be accessed directly from a plugin project's Gradle build script. - The `gradle-intellij-plugin` will access them as-needed for a plugin project. + The [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) will access them as-needed for a plugin project. * Artifacts for individual modules from the IntelliJ Platform. These may be downloaded, or accessed directly from a Gradle build script, as explained below. diff --git a/topics/tutorials/build_system/deployment.md b/topics/tutorials/build_system/deployment.md index 408ffdee6..5cb4b7a39 100644 --- a/topics/tutorials/build_system/deployment.md +++ b/topics/tutorials/build_system/deployment.md @@ -16,7 +16,7 @@ Please see the guide page for manually [publishing a plugin](publishing_plugin.m ## Building Distribution -For initial upload, manual distribution or local installation, invoke the `buildPlugin` Gradle task to create the plugin distribution. +For initial upload, manual distribution or local installation, invoke the [`buildPlugin`](tools_gradle_intellij_plugin.md#buildplugin-task) Gradle task to create the plugin distribution. The resulting ZIP file is located in build/distributions 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). @@ -49,8 +49,8 @@ export ORG_GRADLE_PROJECT_intellijPublishToken='YOUR_TOKEN' > {type="note"} -Now provide the environment variable in the run configuration with which you run the `publishPlugin` task locally. -To do so, create a Gradle run configuration (if not already done), choose your Gradle project, specify the `publishPlugin` task, and then add the environment variable. +Now provide the environment variable in the run configuration with which you run the [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) task locally. +To do so, create a Gradle run configuration (if not already done), choose your Gradle project, specify the [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) task, and then add the environment variable. @@ -96,22 +96,22 @@ You may wish to verify this by [installing your plugin from disk](https://www.je ### Signing a Plugin The Marketplace signing is designed to ensure that plugins are not modified over the course of the publishing and delivery pipeline. -In version `1.x`, the Gradle IntelliJ Plugin provides the `signPlugin` task, which will be executed automatically right before the `publishPlugin`. +In version `1.x`, the Gradle IntelliJ Plugin provides the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) task, which will be executed automatically right before the [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task). -For more details on generating a proper certificate and configuring the `signPlugin` task, check the [Plugin Signing](plugin_signing.md) article. +For more details on generating a proper certificate and configuring the [`signPlugin`](tools_gradle_intellij_plugin.md#signplugin-task) 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. +To deploy a new version of your plugin to the JetBrains Marketplace, invoke the [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) Gradle task. Now check the most recent version of your plugin on the [JetBrains Marketplace](https://plugins.jetbrains.com/). 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. +You may also deploy plugins to a release channel of your choosing, by configuring the [`publishPlugin.channels`](tools_gradle_intellij_plugin.md#publishplugin-task-channels) property. For example: @@ -147,4 +147,4 @@ Popular channel names include: * `beta`: https://plugins.jetbrains.com/plugins/beta/list * `eap`: https://plugins.jetbrains.com/plugins/eap/list -More information about the available configuration options is in the [documentation of the IntelliJ Gradle plugin](https://github.com/JetBrains/gradle-intellij-plugin#publishing-dsl). +More information about the available configuration options is in the [documentation of the IntelliJ Gradle Plugin](tools_gradle_intellij_plugin.md#publishplugin-task). diff --git a/topics/tutorials/build_system/gradle_guide.md b/topics/tutorials/build_system/gradle_guide.md index 548670421..4cf082670 100644 --- a/topics/tutorials/build_system/gradle_guide.md +++ b/topics/tutorials/build_system/gradle_guide.md @@ -12,30 +12,16 @@ It may be useful to review the IntelliJ Platform page, particularly the descript > {type="warning"} -## Overview of the Gradle Plugin +## Overview of the Gradle IntelliJ Plugin -The Gradle plugin is built from the open-source project [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin). +The Gradle plugin is built from the open-source project [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). 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. -When getting started, there are several items to note on the README page: -* At the top of the page, the [latest production version](https://github.com/JetBrains/gradle-intellij-plugin#the-latest-version) of the plugin is listed. - It is advised to upgrade to the latest available version regularly. -* Also, at the top is the minimum required version of Gradle. -* The table of extended Gradle [Tasks](https://github.com/JetBrains/gradle-intellij-plugin#tasks) has a succinct description for each task added by the plugin. - This documentation will focus on the configuration and use four of those tasks: - * [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) - `intellij { ... }`. - * [Running DSL](https://github.com/JetBrains/gradle-intellij-plugin#running-dsl) - `runIde { ... }` - * [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin#patching-dsl) - `patchPluginXml { ... }` - * [Publishing DSL](https://github.com/JetBrains/gradle-intellij-plugin#publishing-dsl) - `publishPlugin { ... }` -* Examples are always a helpful resource, and at the bottom of the page are links to [example](https://github.com/JetBrains/gradle-intellij-plugin#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. - -## Guide to Configuring Gradle Plugin Functionality +## Guide to Configuring Gradle IntelliJ 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 +### Configuring the Gradle IntelliJ 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. @@ -48,19 +34,19 @@ IntelliJ IDEA then indexes the build and any associated source code and JetBrain #### 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. +Explicitly setting the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-type) properties 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_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. +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`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) to point to that installation. +If the [`intellij.localPath`](tools_gradle_intellij_plugin.md#intellij-extension-localpath) attribute is set, do not set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) and [`intellij.type`](tools_gradle_intellij_plugin.md#intellij-extension-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`. -See the Gradle plugin [README](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) for information about specifying the plugin and version. +The Gradle plugin will fetch any plugins in the list defined by [`intellij.plugins`](tools_gradle_intellij_plugin.md#intellij-extension-plugins). +See the Gradle plugin [IntelliJ Extension](tools_gradle_intellij_plugin.md#intellij-extension) for information about specifying the plugin and version. Note that this attribute describes a dependency so that the Gradle plugin can fetch the required artifacts. The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (plugin.xml) file as described in [Plugin Dependencies](plugin_dependencies.md#3-dependency-declaration-in-pluginxml). @@ -73,13 +59,13 @@ 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. -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. +Setting the [`runIde.ideDir`](tools_gradle_intellij_plugin.md#runide-task-idedir) property 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. +A different version of the runtime can be used by specifying the [`runIde.jbrVersion`](tools_gradle_intellij_plugin.md#runide-task-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 @@ -87,46 +73,46 @@ The Gradle plugin will fetch the specified JetBrains Runtime as needed. 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. -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](ide_development_instance.md#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 [`intellij.sandboxDirectory`](tools_gradle_intellij_plugin.md#intellij-extension-sandboxdir) 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](ide_development_instance.md#development-instance-settings-caches-logs-and-plugins) can be controlled using the [`runIde.configDirectory`](tools_gradle_intellij_plugin.md#runide-task), [`runIde.pluginsDirectory`](tools_gradle_intellij_plugin.md#runide-task), and [`runIde.systemDirectory`](tools_gradle_intellij_plugin.md#runide-task) attributes. +If the [`intellij.sandboxDirectory`](tools_gradle_intellij_plugin.md#intellij-extension-sandboxdir) 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. +However, it can be controlled by setting the [`intellij.ideaDependencyCachePath`](tools_gradle_intellij_plugin.md#intellij-extension-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. +As mentioned in the section about [configuring the IntelliJ Platform](#configuring-the-gradle-intellij-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. -There are controls for managing the `gradle-intellij-plugin` version, and the version of Gradle itself. +There are controls for managing the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) version, and the version of Gradle itself. The plugin version is defined in the `plugins {...}` section of a project's Gradle build script. The version of Gradle is defined in $PROJECT_ROOT$/gradle/wrapper/gradle-wrapper.properties. ### Patching the Plugin Configuration File -A plugin project's plugin.xml 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)). +A plugin project's plugin.xml file has element values that are "patched" at build time from the attributes of the [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) 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 Gradle build script_. - * 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 `` 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 a default value,) both attributes are patched at their respective (explicit and default) values. +* If a [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) attribute default value is defined, the attribute value will be patched in plugin.xml _regardless of whether the [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) task appears in the Gradle build script_. + * For example, the default values for the attributes [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) are defined based on the declared (or default) value of [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version). + So by default [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) are substituted into the `` element's `since-build` and `until-build` attributes in the plugin.xml file. +* If a [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) attribute value is explicitly defined, the attribute value will be substituted in plugin.xml. + * If both [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild) and [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) attributes are explicitly set, both are substituted in plugin.xml. + * If one attribute is explicitly set (e.g. [`patchPluginXml.sinceBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-sincebuild)) and one is not (e.g. [`patchPluginXml.untilBuild`](tools_gradle_intellij_plugin.md#patchpluginxml-task-untilbuild) has a default value,) both attributes are patched at their respective (explicit and default) values. * For **no substitution** of the `` element's `since-build` and `until-build` attributes, one of the following must appear in the Gradle build script: - * Either set `intellij.updateSinceUntilBuild = false`, which will disable substituting both `since-build` and `until-build` attributes, + * Either set [`intellij.updateSinceUntilBuild`](tools_gradle_intellij_plugin.md#intellij-extension-updatesinceuntilbuild) to `false`, which will disable substituting both `since-build` and `until-build` attributes, The 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 `patchPluginXml` attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements. +For those [`patchPluginXml`](tools_gradle_intellij_plugin.md#patchpluginxml-task) attributes that contain descriptions such as [`patchPluginXml.changeNotes`](tools_gradle_intellij_plugin.md#patchpluginxml-task-changenotes) and [`patchPluginXml.pluginDescription`](tools_gradle_intellij_plugin.md#patchpluginxml-task-plugindescription), a `CDATA` block is not necessary when using HTML elements. > To maintain and generate an up-to-date changelog, try using [Gradle Changelog Plugin](https://github.com/JetBrains/gradle-changelog-plugin). > {type="tip"} As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](gradle_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 `gradle-intellij-plugin` does not combine and substitute those Gradle properties for the default `` and `` elements in the plugin.xml file. +However, the [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) does not combine and substitute those Gradle properties for the default `` and `` elements in the plugin.xml file. The best practice is to keep `project.version` current. By default, if you modify `project.version` in Gradle build script, the Gradle plugin will automatically update the `` value in the plugin.xml file. @@ -135,15 +121,15 @@ 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 plugin.xml 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. +* [`verifyPlugin`](tools_gradle_intellij_plugin.md#verifyplugin-task) task - validates completeness and contents of plugin.xml descriptors as well as plugin's archive structure, +* [`runPluginVerifier`](tools_gradle_intellij_plugin.md#runpluginverifier-task) task - 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 [](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 [`publishPlugin`](tools_gradle_intellij_plugin.md#publishplugin-task) task. That documentation explains different ways to use Gradle for plugin uploads without exposing account credentials. ## Common Gradle Plugin Configurations for Development @@ -154,15 +140,15 @@ 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. +* Determine the version of [IntelliJ IDEA to use for building the plugin project](#configuring-the-gradle-intellij-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). - * If a production version of IntelliJ IDEA is the desired target, set the `intellij` [version attributes](#intellij-platform-configuration) accordingly. + * If a production version of IntelliJ IDEA is the desired target, set the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) property 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 further attributes need to be set for the IDE Development Instance. This is the default behavior and is the most common use case. * If the plugin project should be run or debugged in an IDE Development Instance based on an alternate version of the IntelliJ Platform, set the [Running](#running-against-alternate-versions-and-types-of-intellij-platform-based-ides) DSL attribute accordingly. * If the plugin project should be run using a JetBrains Runtime other than the default for the IDE Development Instance, specify the [JetBrains Runtime version](#running-against-alternate-versions-of-the-jetbrains-runtime). -* Set the appropriate attributes for [patching the plugin.xml file](#patching-the-plugin-configuration-file). +* Set the appropriate attributes for [patching the plugin.xml file](#patching-the-plugin-configuration-file). ### Plugins Targeting Alternate IntelliJ Platform-Based IDEs diff --git a/topics/tutorials/build_system/gradle_prerequisites.md b/topics/tutorials/build_system/gradle_prerequisites.md index 59fe04be9..5213cef35 100644 --- a/topics/tutorials/build_system/gradle_prerequisites.md +++ b/topics/tutorials/build_system/gradle_prerequisites.md @@ -101,7 +101,7 @@ my_gradle_plugin * 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](plugin_configuration_file.md). -> Please note: the generated build.gradle file needs to be adjusted as shown below, as IntelliJ IDEA currently generates template incompatible with gradle-intellij-plugin 1.0 release. +> Please note: the generated build.gradle file needs to be adjusted as shown below, as IntelliJ IDEA currently generates template incompatible with [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) 1.0 release. > See [Upgrade Instructions](https://lp.jetbrains.com/gradle-intellij-plugin/) for more details. > {type="warning"} @@ -138,14 +138,13 @@ patchPluginXml { * Two plugins to Gradle are explicitly declared: * The [Gradle Java](https://docs.gradle.org/current/userguide/java_plugin.html) plugin. - * The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin/). + * The [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md). * The GroupId from the Wizard [Project Naming/Artifact Coordinates Screen](#project-namingartifact-coordinates-screen) is the `project.group` value. * The Version from the Wizard [Project Naming/Artifact Coordinates Screen](#project-namingartifact-coordinates-screen) is the `project.version` value. * The `sourceCompatibility` line is injected to enforce using Java 8 JDK to compile Java sources. -* 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. +* The value of the [`intellij.version`](tools_gradle_intellij_plugin.md#intellij-extension-version) property 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 placeholder text. +* The value of the [`patchPluginXml.changeNotes`](tools_gradle_intellij_plugin.md#patchpluginxml-task-changenotes) property is set to a placeholder text. #### Plugin Gradle Properties and Plugin Configuration File Elements diff --git a/topics/tutorials/custom_language_support/annotator.md b/topics/tutorials/custom_language_support/annotator.md index 2fb00acc7..9c448a424 100644 --- a/topics/tutorials/custom_language_support/annotator.md +++ b/topics/tutorials/custom_language_support/annotator.md @@ -77,7 +77,7 @@ Using the `com.intellij.annotator` extension point in the plugin configuration f ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. As a test, define the following Java file containing a Simple Language `prefix:value` pair: diff --git a/topics/tutorials/custom_language_support/code_style_settings.md b/topics/tutorials/custom_language_support/code_style_settings.md index c3b6c3bc5..f26122d58 100644 --- a/topics/tutorials/custom_language_support/code_style_settings.md +++ b/topics/tutorials/custom_language_support/code_style_settings.md @@ -59,7 +59,7 @@ The `SimpleLanguageCodeStyleSettingsProvider` implementation is registered with ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. In the IDE Development Instance, open the Simple Language code formatting page: Settings/Preferences | Editor | Code Style | Simple. diff --git a/topics/tutorials/custom_language_support/commenter.md b/topics/tutorials/custom_language_support/commenter.md index 3f3697caf..13602790d 100644 --- a/topics/tutorials/custom_language_support/commenter.md +++ b/topics/tutorials/custom_language_support/commenter.md @@ -29,7 +29,7 @@ The `SimpleCommenter` implementation is registered in the plugin configuration f ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) in the IDE Development Instance. Place the cursor at the `website` line. diff --git a/topics/tutorials/custom_language_support/completion_contributor.md b/topics/tutorials/custom_language_support/completion_contributor.md index e161d3676..8384953cf 100644 --- a/topics/tutorials/custom_language_support/completion_contributor.md +++ b/topics/tutorials/custom_language_support/completion_contributor.md @@ -32,7 +32,7 @@ The `SimpleCompletionContributor` implementation is registered in the plugin con ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the [`test.simple`](lexer_and_parser_definition.md#run-the-project) file. Erase the property "English" and invoke [Basic Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#invoke-basic-completion). diff --git a/topics/tutorials/custom_language_support/find_usages_provider.md b/topics/tutorials/custom_language_support/find_usages_provider.md index adf47bdae..479116908 100644 --- a/topics/tutorials/custom_language_support/find_usages_provider.md +++ b/topics/tutorials/custom_language_support/find_usages_provider.md @@ -33,7 +33,7 @@ The `SimpleFindUsagesProvider` implementation is registered with the IntelliJ Pl ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. The IDE now supports [Find Usages](https://www.jetbrains.com/help/idea/find-highlight-usages.html) for any property with a reference: diff --git a/topics/tutorials/custom_language_support/folding_builder.md b/topics/tutorials/custom_language_support/folding_builder.md index fe437193b..4aadb89f0 100644 --- a/topics/tutorials/custom_language_support/folding_builder.md +++ b/topics/tutorials/custom_language_support/folding_builder.md @@ -43,7 +43,7 @@ The `SimpleFoldingBuilder` implementation is registered with the IntelliJ Platfo ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Now when a Java file is opened in the editor, it shows the property's value instead of the key. This is because `SimpleFoldingBuilder.isCollapsedByDefault()` always returns `true`. diff --git a/topics/tutorials/custom_language_support/formatter.md b/topics/tutorials/custom_language_support/formatter.md index 51bfea9de..d4c75e67c 100644 --- a/topics/tutorials/custom_language_support/formatter.md +++ b/topics/tutorials/custom_language_support/formatter.md @@ -56,7 +56,7 @@ The `SimpleFormattingModelBuilder` implementation is registered with the Intelli ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the example Simple Language [properties file ](lexer_and_parser_definition.md#run-the-project) in the IDE Development Instance. Add some extra spaces around the `=` separator between `language` and `English`. diff --git a/topics/tutorials/custom_language_support/go_to_symbol_contributor.md b/topics/tutorials/custom_language_support/go_to_symbol_contributor.md index ff1662ddd..e82207011 100644 --- a/topics/tutorials/custom_language_support/go_to_symbol_contributor.md +++ b/topics/tutorials/custom_language_support/go_to_symbol_contributor.md @@ -53,7 +53,7 @@ The `SimpleChooseByNameContributor` implementation is registered with the Intell ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. The IDE now supports navigating to a property definition by name pattern via Navigate | Symbol action. diff --git a/topics/tutorials/custom_language_support/language_and_filetype.md b/topics/tutorials/custom_language_support/language_and_filetype.md index 21161695e..60cc5e00a 100644 --- a/topics/tutorials/custom_language_support/language_and_filetype.md +++ b/topics/tutorials/custom_language_support/language_and_filetype.md @@ -92,7 +92,7 @@ The `SimpleFileTypeFactory` is registered using the `com.intellij.fileTypeFactor ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Create an empty file with the extension .simple, and IntelliJ IDEA automatically associates it with our language. Note the appearance of the Simple Language file icon next to the test.simple file in the **Project Tool Window**, and the editor tab for the file. diff --git a/topics/tutorials/custom_language_support/lexer_and_parser_definition.md b/topics/tutorials/custom_language_support/lexer_and_parser_definition.md index f00362948..c13046392 100644 --- a/topics/tutorials/custom_language_support/lexer_and_parser_definition.md +++ b/topics/tutorials/custom_language_support/lexer_and_parser_definition.md @@ -72,7 +72,7 @@ For example, see simple_language_plugin/src/main/resources/META-INF/plugin ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Create a test.simple file with the following content: diff --git a/topics/tutorials/custom_language_support/line_marker_provider.md b/topics/tutorials/custom_language_support/line_marker_provider.md index bcf5e06af..44c7efb78 100644 --- a/topics/tutorials/custom_language_support/line_marker_provider.md +++ b/topics/tutorials/custom_language_support/line_marker_provider.md @@ -88,7 +88,7 @@ The `SimpleLineMarkerProvider` implementation is registered with the IntelliJ Pl ## Run the Project -Run the plugin by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the plugin by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the Java [Test file](annotator.md#run-the-project). Now the icon appears next to line 3 on the gutter. diff --git a/topics/tutorials/custom_language_support/quick_fix.md b/topics/tutorials/custom_language_support/quick_fix.md index 85b38f8ac..6438a76b5 100644 --- a/topics/tutorials/custom_language_support/quick_fix.md +++ b/topics/tutorials/custom_language_support/quick_fix.md @@ -36,7 +36,7 @@ This method call registers the `SimpleCreatePropertyQuickFix` as the Intention A {src="simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java"} ## Run the Project -Run the project by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the test [Java file](annotator.md#run-the-project). To test `SimpleCreatePropertyQuickFix`, change `simple:website` to `simple:website.url`. diff --git a/topics/tutorials/custom_language_support/reference_contributor.md b/topics/tutorials/custom_language_support/reference_contributor.md index 5bcea7b3c..c3fcc37f9 100644 --- a/topics/tutorials/custom_language_support/reference_contributor.md +++ b/topics/tutorials/custom_language_support/reference_contributor.md @@ -137,7 +137,7 @@ The `SimpleReferenceContributor` implementation is registered with the IntelliJ ## Run the Project with the Reference Contributor -Run the project by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. The IDE now resolves the property and provides [completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#basic_completion) suggestions: @@ -171,7 +171,7 @@ The `SimpleRefactoringSupportProvider` implementation is registered with the Int ## Run the Project -Run the project by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. The IDE now supports [refactoring](https://www.jetbrains.com/help/idea/rename-refactorings.html) suggestions: diff --git a/topics/tutorials/custom_language_support/structure_view_factory.md b/topics/tutorials/custom_language_support/structure_view_factory.md index 30ec2cfaf..a9410cf14 100644 --- a/topics/tutorials/custom_language_support/structure_view_factory.md +++ b/topics/tutorials/custom_language_support/structure_view_factory.md @@ -52,7 +52,7 @@ The `SimpleStructureViewFactory` implementation is registered with the IntelliJ ## Run the Project -Run the project by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. Open the test.simple file and choose View | Tool Windows | Structure. The IDE now supports a structure view of the Simple Language: diff --git a/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md b/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md index c70f3c944..1ebc18201 100644 --- a/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md +++ b/topics/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md @@ -82,7 +82,7 @@ Register the Simple Language color settings page with the IntelliJ Platform in t ### Run the Project -Run the project by using the Gradle [runIde task](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin). +Run the project by using the Gradle [`runIde`](gradle_prerequisites.md#running-a-simple-gradle-based-intellij-platform-plugin) task. In the IDE Development Instance, open the Simple Language highlight settings page: Settings/Preferences | Editor | Color Scheme | Simple. Each color initially inherits from a Language Defaults value. diff --git a/topics/tutorials/gradle_build_system.md b/topics/tutorials/gradle_build_system.md index 98b18a75e..0109a3749 100644 --- a/topics/tutorials/gradle_build_system.md +++ b/topics/tutorials/gradle_build_system.md @@ -2,7 +2,7 @@ -The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended solution for building IntelliJ Platform plugins. +The [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) is the recommended solution for building IntelliJ Platform plugins. The plugin takes care of the dependencies of your plugin project — both the base IDE and other [plugin dependencies](plugin_dependencies.md). It provides tasks to run the IDE with your plugin and to package and [publish](deployment.md) 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. @@ -16,7 +16,7 @@ To make sure that a plugin is not affected by [API changes](api_changes_list.md) {type="note"} -> Please make sure to always upgrade `gradle-intellij-plugin` to the latest version [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases) +> Please make sure to always upgrade [Gradle IntelliJ Plugin](tools_gradle_intellij_plugin.md) to the latest version [![GitHub Release](https://img.shields.io/github/release/jetbrains/gradle-intellij-plugin.svg?style=flat-square)](https://github.com/jetbrains/gradle-intellij-plugin/releases) > > See [What's New & Upgrade Instructions](https://lp.jetbrains.com/gradle-intellij-plugin) for upgrading from pre-1.0 versions. >