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

Merge updates about finding library classes

Browse Source
This commit is contained in:
JohnHake 2019-11-21 22:16:25 -08:00
commit a26d3dcc9f
4 changed files with 54 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
basics/getting_started/img/php_prj_libs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 134 KiB

19
basics/getting_started/plugin_compatibility.md
View File

@ -97,6 +97,25 @@ Consequently, Java dependencies are expressed differently in `plugin.xml` depend
* `plugin.xml` _allowable_ alternative include `<depends>com.intellij.java</depends>`
* `build.gradle` _required_ to include `intellij.plugins 'java'`
## Exploring Module and Plugin APIs
Once the [dependency on a module or plugin](/basics/plugin_structure/plugin_dependencies.md#) is declared in `plugin.xml`, it's useful to explore the packages and classes available in that dependency.
The section below gives some recommended procedures for discovering what's available in a module or plugin.
These procedures assume a plugin project has the `build.gradle` and `plugin.xml` dependencies configured correctly.
### Exploring APIs as a Consumer
Exploring the available packages and classes in a plugin or module utilizes features in the IntelliJ IDEA IDE.
If the project is not up to date, [Reimport the Gradle project](https://www.jetbrains.com/help/idea/work-with-gradle-projects.html#gradle_refresh_project) as a first step.
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 `<depends>` tags in `plugin.xml` or the `intellij.plugins` declaration in `build.gradle`.
The image below shows the External Libraries for the example plugin project configuration explained in [Configuring build.gradle](/products/dev_alternate_products.md#configuring-buildgradle-using-the-intellij-idea-product-attribute) and [Configuring plugin.xml](/products/dev_alternate_products.md#configuring-pluginxml).
![Example PhpStorm Project Libraries](img/php_prj_libs.png){:width="700px"}
Expand the External Library (as shown) to reveal the JAR files contained in the library.
Drill down into the JAR files to expose the packages and (decompiled) classes.
## Verifying Dependency
Before marking a plugin project as _dependent only on modules in a target product_ in addition to `com.intellij.modules.platform`, verify the plugin isn't implicitly dependent on any APIs that are specific to IntelliJ IDEA.

54
basics/plugin_structure/plugin_dependencies.md
View File

@ -2,19 +2,22 @@
title: Plugin Dependencies
---
Your plugin may depend on classes from other plugins, either bundled, third-party or your own. In order to express such
dependencies, you need to perform the following three steps:
A plugin may depend on classes from other plugins, either bundled, third-party, or by the same author.
This document describes the syntax for declaring plugin dependencies and optional plugin dependencies.
For more information about dependencies on the IntelliJ Platform modules, see Part II of this document: [Plugin Compatibility with IntelliJ Platform Products](/basics/getting_started/plugin_compatibility.md).
### 1. Preparing Sandbox
If the plugin is not bundled, run the sandbox instance of your target IDE and install the plugin there.
To express dependencies on classes from other plugins or modules, perform the following three required steps:
### 2. Project Setup
Depending on your chosen workflow (Gradle or DevKit), one of the two following steps is necessary.
## 1. Preparing Sandbox
If the plugin is not bundled with the target IDE, run the (sandbox) [IDE Development Instance](/basics/ide_development_instance.md) of your target IDE and install the plugin there.
## 2. Project Setup
Depending on the chosen development workflow (Gradle or DevKit), one of the two following steps is necessary.
### 2.1 Gradle
> **NOTE** Please see the `plugins` attribute [gradle-intellij-plugin: Configuration](https://github.com/JetBrains/gradle-intellij-plugin#configuration) for acceptable values.
If you're using [Gradle](/tutorials/build_system.md) with a Groovy build script to build your plugin, add the dependency to the `plugins` parameter of the `intellij` block in your build.gradle, for example:
If the project is using [Gradle](/tutorials/build_system.md) with a Groovy build script to build the plugin, add the dependency to the `plugins` parameter of the `intellij` block in your build.gradle, for example:
```groovy
intellij {
@ -22,7 +25,7 @@ intellij {
}
```
If you are using [Gradle](/tutorials/build_system.md) with a Kotlin build script to build your plugin, use `setPlugins()` within the `intellij` block, for example:
If the project is using [Gradle](/tutorials/build_system.md) with a Kotlin build script to build the plugin, use `setPlugins()` within the `intellij` block, for example:
```kotlin
intellij {
@ -31,36 +34,39 @@ intellij {
```
#### 2.2 DevKit
If you are using [DevKit](/basics/getting_started/using_dev_kit.md), add the JARs of the plugin you're depending on to the classpath of your *IntelliJ Platform SDK*.
If the project is using [DevKit](/basics/getting_started/using_dev_kit.md), add the JARs of the plugin on which the project depends to the **classpath** of the *IntelliJ Platform SDK*.
> **WARNING** Do not add the plugin JARs as a library: this will fail at runtime because IntelliJ Platform will load two separate copies of the dependency plugin classes.
> **WARNING** Do not add the plugin JARs as a library: this will fail at runtime because the IntelliJ Platform will load two separate copies of the dependency plugin classes.
In order to do that, open the Project Structure dialog, select the SDK you're using, press the + button in the Classpath tab, and
To do that, open the Project Structure dialog, select the SDK used in the project, press the + button in the Classpath tab, and
select the plugin JAR file or files:
* For bundled plugins, the plugin JAR files are located in `plugins/<pluginname>` or `plugins/<pluginname>/lib` under the main installation directory.
If you're not sure, which JAR to add, you can add all of them.
If you're not sure which JAR to add, you can add all of them.
* For non-bundled plugins, the plugin JAR files are located in `config/plugins/<pluginname>` or `config/plugins/<pluginname>/lib` under the directory specified as "Sandbox Home" in the IntelliJ Platform Plugin SDK settings.
![Adding Plugin to Classpath](img/add_plugin_dependency.png)
### 3. Declaration in plugin.xml
In your `plugin.xml`, add a `<depends>` tag with the ID of the dependency plugin as its content (autocompletion is available).
For example:
## 3. Dependency Declaration in plugin.xml
Regardless of whether a plugin project uses [Modules Available in All Products](/basics/getting_started/plugin_compatibility.md#modules-available-in-all-products), or [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality), the correct module must be listed as a dependency in `plugin.xml`.
If a project depends on another plugin, the dependency must be declared like a module.
If only general IntelliJ Platform features (APIs) are used, then a default dependency on `com.intellij.modules.platform` must be declared.
To display a list of available IntelliJ Platform modules, invoke the [code completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#4eac28ba) feature for the `<depends>` element contents while editing the plugin project's `plugin.xml` file.
### 3.1 Configuring plugin.xml
In the `plugin.xml`, add a `<depends>` tag with the ID of the dependency plugin as its content.
Continuing with the example from [Section 2](#2-project-setup) above, the dependency declaration in `plugin.xml` would be:
```xml
<depends>org.jetbrains.kotlin</depends>
```
## Optional Plugin Dependencies
You can also specify an optional plugin dependency. In this case, your plugin will load even if the plugin you depend on
is not installed or enabled, but part of the functionality of your plugin will not be available. In order to do that,
## Optional Plugin Dependencies
A project can also specify an optional plugin dependency. In this case, the plugin will load even if the plugin it depends on
is not installed or enabled, but part of the functionality of the plugin will not be available. In order to do that,
add `optional="true" config-file="otherconfig.xml"` to the `<depends>` tag.
For example,
if you're working on a plugin that adds additional highlighting for Java and Kotlin files, you can use the following setup.
Your main `plugin.xml` will define an annotator for Java and specify an optional dependency on the Kotlin plugin:
For example, if a plugin project adds additional highlighting for Java and Kotlin files, use the following setup.
The main `plugin.xml` will define an annotator for Java and specify an optional dependency on the Kotlin plugin:
```xml
<idea-plugin>
...
@ -72,8 +78,7 @@ Your main `plugin.xml` will define an annotator for Java and specify an optional
</idea-plugin>
```
Then, you create a file called `withKotlin.xml`, in the same directory as your main `plugin.xml` file. In that file, you
define an annotator for Kotlin:
Then create a file called `withKotlin.xml`, in the same directory as the main `plugin.xml` file. In that file, define an annotator for Kotlin:
```xml
<idea-plugin>
<extensions defaultExtensionNs="com.intellij">
@ -81,4 +86,3 @@ define an annotator for Kotlin:
</extensions>
</idea-plugin>
```

8
products/dev_alternate_products.md
View File

@ -117,16 +117,20 @@ This snippet is an example for configuring the Setup and Running DSLs in a `buil
runIde {
// Absolute path to the installed targetIDE to use as IDE Development Instance
// Note the Contents directory must be added at the end of the path for macOS.
ideaDirectory '/Users/jhake/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/192.7142.41/PhpStorm.app/Contents'
ideaDirectory '/Users/<user name>/Library/Application Support/JetBrains/Toolbox/apps/PhpStorm/ch-0/192.7142.41/PhpStorm.app/Contents'
}
```
## Configuring plugin.xml
As discussed on the [Plugin Dependencies](/basics/getting_started/plugin_compatibility.md#declaring-plugin-dependencies) page of this guide, a plugin's dependency on [Modules Specific to Functionality](/basics/getting_started/plugin_compatibility.md#modules-specific-to-functionality) must be declared in `plugin.xml`.
When using product-specific features (APIs), a dependency on the product module must be declared, as shown in the code snippet below.
When using features (APIs) specific to the target product, a dependency on the target product module must be declared, as shown in the code snippet below.
Otherwise, if only general IntelliJ Platform features (APIs) are used, then a dependency on `com.intellij.modules.platform` must be declared as discussed in [Plugin Compatibility with IntelliJ Platform Products](/basics/getting_started/plugin_compatibility.md).
> **NOTE** In the special case of a plugin project declaring dependencies only on other plugins, it must also declare a dependency on `com.intellij.modules.platform`. Otherwise, the plugin project is considered to be legacy and will only load in IntelliJ IDEA.
Continuing with the example of developing a plugin for PhpStorm:
```xml
<!-- Targeting PhpStorm, so is dependent on the PHP plugin -->
<depends>com.jetbrains.php</depends>
<depends>com.intellij.modules.platform</depends>
```