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

gradle: formatting

Browse Source
This commit is contained in:
Yann Cébron 2021-05-03 15:07:34 +02:00
parent 1a8f3a18bf
commit e2a8148b2a
2 changed files with 28 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
topics/tutorials/build_system/gradle_guide.md
View File

@ -36,7 +36,7 @@ This section presents a guided tour of Gradle plugin attributes to achieve the c
### Configuring the Gradle Plugin for Building IntelliJ Platform Plugin Projects
By default, the Gradle plugin will build a plugin project against the IntelliJ Platform defined by the latest EAP snapshot of the IntelliJ IDEA Community Edition.
> Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the `build.gradle` file (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)).
> Using EAP versions of the IntelliJ Platform requires adding the _Snapshots repository_ to the <path>build.gradle</path> file (see [IntelliJ Platform Artifacts Repositories](intellij_artifacts.md)).
>
{type="note"}
@ -58,7 +58,7 @@ The Gradle plugin will fetch any plugins in the list defined by `intellij.plugin
See the Gradle plugin [README](https://github.com/JetBrains/gradle-intellij-plugin#setup-dsl) 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#dependency-declaration-in-pluginxml).
The runtime dependency must be added in the [Plugin Configuration](plugin_configuration_file.md) (<path>plugin.xml</path>) file as described in [Plugin Dependencies](plugin_dependencies.md#dependency-declaration-in-pluginxml).
### Configuring the Gradle Plugin for Running IntelliJ Platform Plugin Projects
By default, the Gradle plugin will use the same version of the IntelliJ Platform for the IDE Development Instance as was used for building the plugin.
@ -90,23 +90,23 @@ As mentioned in the section about [configuring the IntelliJ Platform](#configuri
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.
The plugin version is defined in the `plugins {}` section of a project's `build.gradle` file.
The version of Gradle is defined in `<PROJECT ROOT>/gradle/wrapper/gradle-wrapper.properties`.
The plugin version is defined in the `plugins {}` section of a project's <path>build.gradle</path> file.
The version of Gradle is defined in <path><PROJECT ROOT>/gradle/wrapper/gradle-wrapper.properties</path>.
### Patching the Plugin Configuration File
A plugin project's `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)).
As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's `plugin.xml` file:
* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in `plugin.xml` _regardless of whether the `patchPluginXml` task appears in the `build.gradle` file_.
A plugin project's <path>plugin.xml</path> file has element values that are "patched" at build time from the attributes of the `patchPluginXml` task ([Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin#patching-dsl)).
As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's <path>plugin.xml</path> file:
* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in <path>plugin.xml</path> _regardless of whether the `patchPluginXml` task appears in the <path>build.gradle</path> file_.
* For example, the default values for the attributes `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are defined based on the declared (or default) value of `intellij.version`.
So by default `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are substituted into the `<idea-version>` element's `since-build` and `until-build` attributes in the `plugin.xml` file.
* If a `patchPluginXml` attribute value is explicitly defined, the attribute value will be substituted in `plugin.xml`.
* If both `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` attributes are explicitly set, both are substituted in `plugin.xml`.
So by default `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are substituted into the `<idea-version>` element's `since-build` and `until-build` attributes in the <path>plugin.xml</path> file.
* If a `patchPluginXml` attribute value is explicitly defined, the attribute value will be substituted in <path>plugin.xml</path>.
* If both `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` attributes are explicitly set, both are substituted in <path>plugin.xml</path>.
* 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.
* For **no substitution** of the `<idea-version>` element's `since-build` and `until-build` attributes, one of the following must appear in the `build.gradle` file:
* For **no substitution** of the `<idea-version>` element's `since-build` and `until-build` attributes, one of the following must appear in the <path>build.gradle</path> file:
* Either set `intellij.updateSinceUntilBuild = false`, which will disable substituting both `since-build` and `until-build` attributes,
* Or, for independent control, set `patchPluginXml.sinceBuild(null)` and `patchPluginXml.untilBuild(null)` depending on whether the intention is to disable one or both substitutions.
A best practice to avoid confusion is to replace the elements in `plugin.xml` that will be patched by the Gradle plugin with a comment.
A best practice to avoid confusion is to replace the elements in <path>plugin.xml</path> that will be patched by the Gradle plugin with a comment.
That way the values for these parameters do not appear in two places in the source code.
The 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.
@ -116,15 +116,15 @@ For those `patchPluginXml` attributes that contain descriptions such as `changeN
{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 `<id>` and `<name>` elements in the `plugin.xml` file.
However, the `gradle-intellij-plugin` does not combine and substitute those Gradle properties for the default `<id>` and `<name>` elements in the <path>plugin.xml</path> file.
The best practice is to keep `project.version` current.
By default, if you modify `project.version` in `build.gradle`, the Gradle plugin will automatically update the `<version>` value in the `plugin.xml` file.
By default, if you modify `project.version` in <path>build.gradle</path>, the Gradle plugin will automatically update the `<version>` value in the <path>plugin.xml</path> file.
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,
- `verifyPlugin` - validates completeness and contents of <path>plugin.xml</path> descriptors as well as plugin’s archive structure,
- `runPluginVerifier` - runs the [IntelliJ Plugin Verifier](https://github.com/JetBrains/intellij-plugin-verifier) tool to check the binary compatibility with specified IntelliJ IDE builds.
Plugin Verifier integration task allows for configuring the exact IDE versions that your plugin will be checked against.
@ -148,7 +148,7 @@ IntelliJ Platform plugins targeting IntelliJ IDEA have the most straightforward
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
Gradle also supports developing plugins to run in IDEs that are based on the IntelliJ Platform.

24
topics/tutorials/build_system/gradle_prerequisites.md
View File

@ -47,7 +47,7 @@ Optionally:
* To include support for the Kotlin language in the plugin, check the _Kotlin/JVM_ box (circled in green below).
This option can be selected with or without the _Java_ language.
See [Kotlin for Plugin Developers](kotlin.md) for more information.
* To create the `build.gradle` file as a Kotlin build script (`build.gradle.kts`) rather than Groovy, check the _Kotlin DSL build script_ box (circled in magenta below).
* To create the <path>build.gradle</path> file as a Kotlin build script (<path>build.gradle.kts</path>) rather than Groovy, check the _Kotlin DSL build script_ box (circled in magenta below).
Then click _Next_:
@ -55,12 +55,12 @@ Then click _Next_:
### Project Naming/Artifact Coordinates Screen
Expand the _Artifact Coordinates_ section and specify a [GroupId, ArtifactId, and Version](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle) using [Maven naming](https://maven.apache.org/guides/mini/guide-naming-conventions.html) conventions.
* _GroupId_ is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's `build.gradle` file.
* _GroupId_ is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's <path>build.gradle</path> file.
For this example, enter `com.your.company`.
* _ArtifactId_ is the default name of the project JAR file (without version).
It is also used for the Gradle property `rootProject.name` value in the project's `settings.gradle` file.
It is also used for the Gradle property `rootProject.name` value in the project's <path>settings.gradle</path> file.
For this example, enter `my_gradle_plugin`.
* _Version_ is used for the Gradle property `project.version` value in the `build.gradle` file.
* _Version_ is used for the Gradle property `project.version` value in the <path>build.gradle</path> file.
For this example, enter `1.0`.
The _Name_ field is synced automatically with the specified _ArtifactId_.
@ -91,13 +91,13 @@ my_gradle_plugin
└── resources
```
* The default IntelliJ Platform `build.gradle` file (see next paragraph).
* The default IntelliJ Platform <path>build.gradle</path> file (see next paragraph).
* The Gradle Wrapper files, and in particular the `gradle-wrapper.properties` file, which specifies the version of Gradle to be used to build the plugin.
If needed, the IntelliJ IDEA Gradle plugin downloads the version of Gradle specified in this file.
* The `settings.gradle` file, containing a definition of the `rootProject.name`.
* The `META-INF` directory under the default `main` [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](plugin_configuration_file.md).
* The <path>settings.gradle</path> file, containing a definition of the `rootProject.name`.
* The <path>META-INF</path> 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).
The generated `my_gradle_plugin` project `build.gradle` file:
The generated `my_gradle_plugin` project <path>build.gradle</path> file:
```groovy
plugins {
@ -139,7 +139,7 @@ The generated `my_gradle_plugin` project `build.gradle` file:
* The value of the Patching DSL attribute `patchPluginXml.changeNotes` is set to a place holder text.
#### Plugin Gradle Properties and Plugin Configuration File Elements
The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective [plugin configuration file](plugin_configuration_file.md) `plugin.xml` elements `<name>` and `<id>`.
The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective [plugin configuration file](plugin_configuration_file.md) <path>plugin.xml</path> elements `<name>` and `<id>`.
There is no IntelliJ Platform-related reason they should as they serve different functions.
The `<name>` element (used as the plugin's display name) is often the same as `rootProject.name`, but it can be more explanatory.
@ -151,9 +151,9 @@ Please note that it is impossible to change the `<id>` of a published plugin wit
Converting a [DevKit-based](using_dev_kit.md) plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project:
* Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
* Delete all the artifacts of the DevKit-based project:
* `.idea` directory
* `[modulename].iml` file
* `out` directory
* <path>.idea</path> directory
* <path>[modulename].iml</path> file
* <path>out</path> directory
* Arrange the existing source files within the project directory in the Gradle [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) format.
* Use the New Project Wizard as though creating a [new Gradle project](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) from scratch.
* On the [Project Naming/Artifact Coordinates Screen](#project-namingartifact-coordinates-screen) set the values to: