Skip to content

Latest commit

 

History

History
350 lines (268 loc) · 50.5 KB

README.md

File metadata and controls

350 lines (268 loc) · 50.5 KB
Raw

official JetBrains project Gradle Plugin Portal Build Status Twitter Follow Slack

Gradle IntelliJ Plugin

gradle-intellij-plugin

The latest version is 1.3.0

Important:

  • This project requires Gradle 6.6 or newer, however it is recommended to use the latest Gradle available. Update it with: 
    ./gradlew wrapper --gradle-version=VERSION
  • Gradle JVM should be set to Java 11 (see Settings/Preferences | Build, Execution, Deployment | Build Tools | Gradle)

When upgrading to 1.x version, please make sure to follow migration guide to adjust your existing build script: https://lp.jetbrains.com/gradle-intellij-plugin

This plugin allows you to build plugins for IntelliJ Platform using specified IntelliJ SDK and bundled/3rd-party plugins.

The plugin adds extra IntelliJ-specific dependencies, patches processResources tasks to fill some tags (name, version) in plugin.xml 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.

Getting started

TIP Create new plugins with a preconfigured project scaffold and CI using IntelliJ Platform Plugin Template.

Here is the manual on how to start developing plugins for the IntelliJ Platform using Gradle.

Also, please take a look at the FAQ.

Usage

Gradle

plugins {
  id "org.jetbrains.intellij" version "1.3.0"
}

Snapshot version

To get the latest features, use the snapshot version of the plugin 
plugins {
  id "org.jetbrains.intellij" version "1.4.0-SNAPSHOT"
}

And define the snapshot repository in your settings.gradle file

pluginManagement {
    repositories {
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots/'
        }
        gradlePluginPortal()
    }
}

Tasks

Plugin introduces the following tasks

Task Description
buildPlugin Assembles plugin and prepares ZIP archive for deployment.
patchPluginXml Collects all plugin.xml files in sources and fill since/until build and version attributes.
downloadRobotServerPlugin Downloads robot-server plugin which is needed for ui tests running.
prepareSandbox Creates proper structure of plugin, copies patched plugin xml files and fills sandbox directory with all of it.
prepareTestingSandbox Prepares sandbox that will be used while running tests.
prepareUiTestingSandbox Prepares sandbox that will be used while running ui tests.
buildSearchableOptions Builds an index of UI components (a.k.a. searchable options) for the plugin by running a headless IDE instance.
Note, that this is a runIde task with predefined arguments and all properties of runIde task are also applied to buildSearchableOptions tasks.
jarSearchableOptions Creates a jar file with searchable options to be distributed with the plugin.
runIde Executes an IntelliJ IDEA instance with the plugin you are developing.
runIdeForUiTests Executes an IntelliJ IDEA instance ready for ui tests run with the plugin you are developing. See intellij-ui-test-robot project to know more
publishPlugin Uploads plugin distribution archive to https://plugins.jetbrains.com.
runPluginVerifier Runs the IntelliJ Plugin Verifier tool to check the binary compatibility with specified IntelliJ IDE builds.
verifyPlugin Validates completeness and contents of plugin.xml descriptors as well as plugin’s archive structure.
signPlugin Signs the ZIP archive with the provided key using marketplace-zip-signer library.
listProductsReleases Lists the available IDE binary releases that could be used with the Plugin Verifier.

Configuration

Plugin provides the following options to configure target IntelliJ SDK and build archive

Setup DSL

The following attributes are a part of the Setup DSL intellij { ... } in which allows you to set up the environment and dependencies.

Attributes Values
pluginName - The name of the target zip-archive and defines the name of plugin artifact. Acceptable Values:
String - 'gradle-intellij-plugin'

Default Value: $project.name

IntelliJ Platform Properties

Attributes Values
version REQUIRED - The version of the IntelliJ Platform IDE that will be used to build the plugin.

Please see Plugin Compatibility in SDK docs for more details.

Notes:
  • Value may have IC-, IU-, CL-, PY-, PC-, RD-, GO- or JPS- prefix in order to define IDE distribution type.
  • intellij.version and intellij.localPath should not be specified at the same time.
 Acceptable Values:
  • version #
    '2017.2.5' or 'IC-2017.2.5'
  • build #
    '172.4343' or 'IU-172.4343'
  • 'LATEST-EAP-SNAPSHOT'


All available JetBrains IDEs versions can be found at IntelliJ Artifacts page.
type - The type of IDE distribution. Acceptable Values:
  • 'IC' - IntelliJ IDEA Community Edition.
  • 'IU' - IntelliJ IDEA Ultimate Edition.
  • 'CL' - CLion.
  • 'PY' - PyCharm Professional Edition.
  • 'PC' - PyCharm Community Edition.
  • 'RD' - Rider.
  • 'GO' - GoLand.
  • 'JPS' - JPS-only.
Default Value: 'IC'
localPath - The path to locally installed IDE distribution that should be used as a dependency.

Notes:
  • intellij.version and intellij.localPath should not be specified at the same time.
 Acceptable Values:
path - '/Applications/IntelliJIDEA.app'

Default Value: null
plugins - The list of bundled IDE plugins and plugins from the JetBrains Plugin Repository.

Please see Plugin Dependencies in SDK docs for more details.

Notes:
  • For plugins from the JetBrains Plugin Repository use format pluginId:version.
  • For bundled plugins version should be omitted: e.g. org.intellij.groovy for IDEA/plugins/Groovy plugin.
  • For sub-projects 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.
 Acceptable Values:
  1. org.plugin.id:version[@channel]
    'org.intellij.plugins.markdown:8.5.0', 'org.intellij.scala:2017.2.638@nightly'
  2. bundledPluginName
    'android', 'Groovy'
  3. project(':projectName')
    project(':plugin-subproject')
Default Value: none

Building Properties

Attributes Values
updateSinceUntilBuild - Should plugin patch plugin.xml with since and until build values?

Notes:
  • If true then user-defined values from patchPluginXml.sinceBuild and patchPluginXml.untilBuild will be used (or their default values if none set).
Acceptable Values: true false

Default Value: true
sameSinceUntilBuild - Should plugin patch plugin.xml with an until build value that is just an "open" since build?

Notes:
  • Is useful for building plugins against EAP IDE builds.
  • If true then the user-defined value from patchPluginXml.sinceBuild (or its default value) will be used as a since and an "open" until value.
  • If patchPluginXml.untilBuild has a value set, then sameSinceUntilBuild is ignored.
 Acceptable Values: true false

Default Value: false
instrumentCode - Should plugin instrument java classes with nullability assertions and compile forms created by IntelliJ GUI Designer? Acceptable Values: true false

Default Value: true

Run/Debug IDE Properties

Attributes Values
sandboxDir - The path of sandbox directory that is used for running IDE with developing plugin. Acceptable Values:
path - '${project.rootDir}/.sandbox'

Default Value: '${project.buildDir}/idea-sandbox'

Infrastructure Properties

Attributes Values
intellijRepository, jreRepository - Urls of repositories for downloading IDE distributions and JetBrains Java Runtime.

Acceptable Values:
url

Default Value: https://jetbrains.com/intellij-repository, https://cache-redirector.jetbrains.com/intellij-jbr
pluginsRepositories { ... } - Configure repositories for downloading plugin dependencies.

Configuration:
marketplace() - use Maven repository with plugins listed in the JetBrains marketplace
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

Default Configuration: pluginsRepositories { marketplace() }
downloadSources - Should plugin download IntelliJ sources while initializing Gradle build?

Notes:
  • Since sources are not needed while testing on CI, you can set it to false for a particular environment.
 Acceptable Values: true false

Default Value: true if CI environment variable is not set
ideaDependencyCachePath - The absolute path to the local directory that should be used for storing IDE distributions.

Notes:
  • Empty value means the Gradle cache directory will be used.
 Acceptable Values:
path - '<example>'

Default Value: none

Running DSL

RunIde tasks (both runIde and buildSearchableOptions) extend JavaExec Gradle task, all configuration attributes of JavaExec task can be used in RunIde as well.

In addition to that, following attributes may be used to customize IDE running:

Attributes Default Value
jbrVersion JetBrains Java runtime version to use when running the IDE with the plugin. Acceptable Values: String - E.g. '8u112b752.4', '8u202b1483.24', or '11_0_2b159'. Prefixes jbrex, jbrx or jbr are allowed.

All JetBrains Java versions are available at JetBrains Space Packages, and GitHub.

Default Value: null for IDE < 2017.3, builtin java version for IDE >= 2017.3
ideDir Path to IDE distribution that will be used to run the IDE with the plugin. path to IDE-dependency
configDir Path to configuration directory. ${intellij.sandboxDir}/config
pluginsDir Path to plugins directory. ${intellij.sandboxDir}/plugins
systemDir Path to indexes directory. ${intellij.sandboxDir}/system
autoReloadPlugins Enable/disable auto-reload of dynamic plugins. true for IDE >= 2020.2

Patching DSL

The following attributes are a part of the Patching DSL patchPluginXml { ... } in which allows Gradle to patch specific attributes in a set of plugin.xml files.

TIP To maintain and generate an up-to-date changelog, try using Gradle Changelog Plugin.

Attributes Default Value
version is a value for the <version> tag. project.version
sinceBuild is for the since-build attribute of the <idea-version> tag. intellij.version in Branch.Build.Fix format
untilBuild is for the until-build attribute of the <idea-version> tag. intellij.version in Branch.Build.* format
pluginDescription is for the <description> tag. none
changeNotes is for the <change-notes> tag. none
pluginXmlFiles is a collection of xml files to patch. All plugin.xml files with <idea-plugin>
destinationDir is a directory to store patched xml files. '${project.buildDir}/patchedPluginXmlFiles'

Plugin Verifier DSL

IntelliJ Plugin Verifier integration task allows to check the binary compatibility of the built plugin against the specified IntelliJ IDE builds.

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 by proxifying them to the Verifier CLI.

TIP For more details, examples or issues reporting, go to the IntelliJ Plugin Verifier repository.

Attributes Default Value
ideVersions - IDEs to check, in intellij.version format, i.e.: ["IC-2019.3.5", "PS-2019.3.2"]. Check the available build versions on https://jb.gg/intellij-platform-builds-list none
verifierVersion - IntelliJ Plugin Verifier version, by default uses the latest available. It's recommended to use always the latest version. latest
verifierPath - IntelliJ Plugin Verifier local path to the pre-downloaded jar file. If set, verifierVersion is ignored. none
localPaths - A list of the paths to locally installed IDE distributions that should be used for verification in addition to those specified in ideVersions. []
distributionFile - Jar or Zip file of plugin to verify. output of buildPlugin task
failureLevel - Defines the verification level at which task should fail. Can be set as FailureLevel enum or EnumSet<FailureLevel>. FailureLevel.INVALID_PLUGIN
verificationReportsDir - The path to directory where verification reports will be saved. ${project.buildDir}/reports/pluginVerifier
downloadDir - The path to directory where IDEs used for the verification will be downloaded. System.getProperty("plugin.verifier.home.dir")/ides or System.getProperty("user.home")/.pluginVerifier/ides or system temporary directory.
jbrVersion - JBR version used by the Verifier. none
runtimeDir - The path to directory containing Java runtime, overrides JBR. none
externalPrefixes - The prefixes of classes from the external libraries. none
teamCityOutputFormat - Specify this flag if you want to print the TeamCity compatible output on stdout. none
subsystemsToCheck - Specifies which subsystems of IDE should be checked. Available options: all (default), android-only, without-android. none

TIP To run Plugin Verifier in -offline mode, set the Gradle offline start parameter.

Plugin Signing

To sign the plugin before publishing to the JetBrains Marketplace with the signPlugin task, it is required to provide a certificate chain and a private key with its password using signPlugin { ... } Plugin Signing DSL.

As soon as privateKey (or privateKeyFile) and certificateChain (or certificateChainFile) properties are specified, task will be executed automatically right before the publishPlugin task.

Attributes Default Value
certificateChain A string containing X509 certificates. none
certificateChainFile Path to the file containing X509 certificates. none
privateKey Encoded private key in PEM format. none
privateKeyFile Path to the file with encoded private key in PEM format. none
password Password required to decrypt private key. none
cliVersion Version of the Marketplace ZIP Signer CLI to use. LATEST
cliPath Path to the Marketplace ZIP Signer CLI file. Takes a precedence over the cliPath. none
keyStore KeyStore file path. none
keyStorePassword KeyStore password. none
keyStoreKeyAlias KeyStore key alias. none
keyStoreType KeyStore type. none
keyStoreProviderName JCA KeyStore Provider name. none

List Products Releases

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 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 types, sinceVersion, untilVersion properties.

The result list is stored within the outputFile, which is used as a source for the Plugin Verifier if the runPluginVerifier task has no ideVersions property specified, the output of the listProductsReleases is used.

Attributes Default Value
updatesFile Path to the products releases update file. By default, falls back to the Maven cache. Maven cache
types List of types of IDEs that will be listed in results. Uses intellij.type by default. [intellij.type]
sinceVersion Lower boundary of the listed results. Uses intellij.version by default. intellij.version
untilVersion Upper boundary of the listed results. none
releaseChannels Defines channels that product updates will be filtered with. EnumSet.allOf(ListProductsReleasesTask.Channel)
outputFile Path to the file, where the output list will be stored. File("${project.buildDir}/listProductsReleases.txt")

Publishing DSL

The following attributes are a part of the Publishing DSL publishPlugin { ... } in which allows Gradle to upload a working plugin to the JetBrains Plugin Repository. Note that you need to upload the plugin 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 tutorial for step-by-step instructions.

Attributes Default Value
token Authentication token. none
channels List of channel names to upload plugin to. [default]
host URL host of a plugin repository. https://plugins.jetbrains.com
distributionFile Jar or Zip file of plugin to upload. output of buildPlugin task

Instrumenting DSL

The following attributes help you to tune instrumenting behaviour in instrumentCode { ... } block.

Attributes Default Value
compilerVersion is a version of instrumenting compiler. It's used for non-IDEA plugins (e.g. CLion or Rider). Build number of the IDE dependency

Examples

Marketplace platform provides the IntelliJ Platform Explorer – a search tool for browsing Extension Points inside existing implementations of open-source IntelliJ Platform plugins.

One of its features is the possibility of filtering the plugins by those that utilize Gradle or Gradle KTS build scripts.

As examples of using this plugin, you can also check out following projects:

Contributing

Contributing tips:

You can debug the source code of gradle-intellij-plugin (e.g. put breakpoints there) if you add a reference to your local copy into settings.gradle of your IntelliJ plugin:

includeBuild '/path/to/gradle-intellij-plugin'

License

Copyright 2021 org.jetbrains.intellij.plugins

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

--

This README.md file was hand-crafted with care utilising synapticlooptemplar->documentr

--