diff --git a/basics/getting_started/img/php_prj_libs.png b/basics/getting_started/img/php_prj_libs.png new file mode 100644 index 000000000..d78929090 Binary files /dev/null and b/basics/getting_started/img/php_prj_libs.png differ diff --git a/basics/getting_started/plugin_compatibility.md b/basics/getting_started/plugin_compatibility.md index d2137ca73..3a80e98a1 100644 --- a/basics/getting_started/plugin_compatibility.md +++ b/basics/getting_started/plugin_compatibility.md @@ -97,6 +97,25 @@ Consequently, Java dependencies are expressed differently in `plugin.xml` depend * `plugin.xml` _allowable_ alternative include `com.intellij.java` * `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 `` 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. diff --git a/basics/plugin_structure/plugin_dependencies.md b/basics/plugin_structure/plugin_dependencies.md index e88ed3318..70c08c4d1 100644 --- a/basics/plugin_structure/plugin_dependencies.md +++ b/basics/plugin_structure/plugin_dependencies.md @@ -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). + +To express dependencies on classes from other plugins or modules, perform the following three required steps: -### 1. Preparing Sandbox -If the plugin is not bundled, run the sandbox instance of your target IDE and install the plugin there. +## 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 your chosen workflow (Gradle or DevKit), one of the two following steps is necessary. +## 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/` or `plugins//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/` or `config/plugins//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 `` 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 `` element contents while editing the plugin project's `plugin.xml` file. +### 3.1 Configuring plugin.xml +In the `plugin.xml`, add a `` 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 org.jetbrains.kotlin ``` -## 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 `` 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 ... @@ -72,8 +78,7 @@ Your main `plugin.xml` will define an annotator for Java and specify an optional ``` -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 @@ -81,4 +86,3 @@ define an annotator for Kotlin: ``` - diff --git a/products/dev_alternate_products.md b/products/dev_alternate_products.md index 9054ad1da..184db0783 100644 --- a/products/dev_alternate_products.md +++ b/products/dev_alternate_products.md @@ -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//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 com.jetbrains.php + com.intellij.modules.platform ```