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 pull request #180 from JohnHake/IJSDK-473mstr

Browse Source
This commit is contained in:
John Hake 2019-06-19 09:36:50 -07:00 committed by GitHub
commit 2c28bd176d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 862 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -37,6 +37,7 @@ _includes
### Gradle template
.gradle
build/
_idea-sandbox/
# Ignore Gradle GUI config
gradle-app.setting

16
.idea/gradle.xml generated
View File

@ -2,6 +2,17 @@
<project version="4">
<component name="GradleSettings">
<option name="linkedExternalProjectsSettings">
<GradleProjectSettings>
<option name="distributionType" value="DEFAULT_WRAPPED" />
<option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/action_basics" />
<option name="gradleHome" value="C:/Program Files (x86)/Gradle/gradle-2.9" />
<option name="gradleJvm" value="1.8 202b1483.58" />
<option name="modules">
<set>
<option value="$PROJECT_DIR$/code_samples/action_basics" />
</set>
</option>
</GradleProjectSettings>
<GradleProjectSettings>
<option name="distributionType" value="DEFAULT_WRAPPED" />
<option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/gradle_plugin_demo" />
@ -12,11 +23,6 @@
<option value="$PROJECT_DIR$/code_samples/gradle_plugin_demo" />
</set>
</option>
<option name="myModules">
<set>
<option value="$PROJECT_DIR$/code_samples/gradle_plugin_demo" />
</set>
</option>
</GradleProjectSettings>
</option>
</component>

1
.idea/intellij-sdk-docs.iml generated
View File

@ -5,6 +5,7 @@
<excludeFolder url="file://$MODULE_DIR$/.bundle" />
<excludeFolder url="file://$MODULE_DIR$/.git-metadata" />
<excludeFolder url="file://$MODULE_DIR$/_site" />
<excludeFolder url="file://$MODULE_DIR$/code_samples/_idea-sandbox" />
</content>
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />

7
.idea/misc.xml generated
View File

@ -1,10 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="EntryPointsManager">
<entry_points version="2.0" />
</component>
<component name="ExternalStorageConfigurationManager" enabled="true" />
<component name="ProjectRootManager" version="2" languageLevel="JDK_1_7" default="false" assert-keyword="true" jdk-15="true" project-jdk-name="IntelliJ IDEA IU-144.3600.7" project-jdk-type="IDEA JDK">
<output url="file://$PROJECT_DIR$/build" />
<component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IU-191.7479.19" project-jdk-type="IDEA JDK">
<output url="file://$PROJECT_DIR$/Build" />
</component>
</project>

1
_SUMMARY.md
View File

@ -19,6 +19,7 @@
* [Getting Started](basics/getting_started.md)
* [Using Gradle](tutorials/build_system.md)
* [Getting Started with Gradle](tutorials/build_system/prerequisites.md)
* [Configuring Gradle Projects](tutorials/build_system/gradle_guide.md)
* [Publishing Your Plugin](tutorials/build_system/deployment.md)
* [Using DevKit](basics/getting_started/using_dev_kit.md)
* [Setting Up a Development Environment](basics/getting_started/setting_up_environment.md)

11
code_samples/action_basics/.gitignore vendored Normal file
View File

@ -0,0 +1,11 @@
# Created by .ignore support plugin (hsz.mobi)
### Gradle template
.gradle
build/
# Ignore Gradle GUI config
gradle-app.setting
# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
!gradle-wrapper.jar

30
code_samples/action_basics/build.gradle Normal file
View File

@ -0,0 +1,30 @@
plugins {
id 'java'
id 'org.jetbrains.intellij' version '0.4.8'
}
sourceCompatibility = 1.8
repositories {
mavenCentral()
}
dependencies {
testCompile group: 'junit', name: 'junit', version: '4.12'
}
// See https://github.com/JetBrains/gradle-intellij-plugin/
intellij {
// Define IntelliJ Platform API version to use for building this plugin
version '2019.1'
// Prevents patching <idea-version> attributes in plugin.xml
updateSinceUntilBuild = false
// Define a shared sandbox directory for running code sample plugins within an IDE.
sandboxDirectory = file("${project.projectDir}/../_idea-sandbox")
}
// Force javadoc rebuild before jar is built
jar.dependsOn javadoc

BIN
code_samples/action_basics/gradle/wrapper/gradle-wrapper.jar vendored Normal file
View File

Binary file not shown.

5
code_samples/action_basics/gradle/wrapper/gradle-wrapper.properties vendored Normal file
View File

@ -0,0 +1,5 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.3-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

172
code_samples/action_basics/gradlew vendored Executable file
View File

@ -0,0 +1,172 @@
#!/usr/bin/env sh
##############################################################################
##
## Gradle start up script for UN*X
##
##############################################################################
# Attempt to set APP_HOME
# Resolve links: $0 may be a link
PRG="$0"
# Need this for relative symlinks.
while [ -h "$PRG" ] ; do
ls=`ls -ld "$PRG"`
link=`expr "$ls" : '.*-> \(.*\)$'`
if expr "$link" : '/.*' > /dev/null; then
PRG="$link"
else
PRG=`dirname "$PRG"`"/$link"
fi
done
SAVED="`pwd`"
cd "`dirname \"$PRG\"`/" >/dev/null
APP_HOME="`pwd -P`"
cd "$SAVED" >/dev/null
APP_NAME="Gradle"
APP_BASE_NAME=`basename "$0"`
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
DEFAULT_JVM_OPTS=""
# Use the maximum available, or set MAX_FD != -1 to use that value.
MAX_FD="maximum"
warn () {
echo "$*"
}
die () {
echo
echo "$*"
echo
exit 1
}
# OS specific support (must be 'true' or 'false').
cygwin=false
msys=false
darwin=false
nonstop=false
case "`uname`" in
CYGWIN* )
cygwin=true
;;
Darwin* )
darwin=true
;;
MINGW* )
msys=true
;;
NONSTOP* )
nonstop=true
;;
esac
CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
# Determine the Java command to use to start the JVM.
if [ -n "$JAVA_HOME" ] ; then
if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
# IBM's JDK on AIX uses strange locations for the executables
JAVACMD="$JAVA_HOME/jre/sh/java"
else
JAVACMD="$JAVA_HOME/bin/java"
fi
if [ ! -x "$JAVACMD" ] ; then
die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation."
fi
else
JAVACMD="java"
which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation."
fi
# Increase the maximum file descriptors if we can.
if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
MAX_FD_LIMIT=`ulimit -H -n`
if [ $? -eq 0 ] ; then
if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
MAX_FD="$MAX_FD_LIMIT"
fi
ulimit -n $MAX_FD
if [ $? -ne 0 ] ; then
warn "Could not set maximum file descriptor limit: $MAX_FD"
fi
else
warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
fi
fi
# For Darwin, add options to specify how the application appears in the dock
if $darwin; then
GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
fi
# For Cygwin, switch paths to Windows format before running java
if $cygwin ; then
APP_HOME=`cygpath --path --mixed "$APP_HOME"`
CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
JAVACMD=`cygpath --unix "$JAVACMD"`
# We build the pattern for arguments to be converted via cygpath
ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
SEP=""
for dir in $ROOTDIRSRAW ; do
ROOTDIRS="$ROOTDIRS$SEP$dir"
SEP="|"
done
OURCYGPATTERN="(^($ROOTDIRS))"
# Add a user-defined pattern to the cygpath arguments
if [ "$GRADLE_CYGPATTERN" != "" ] ; then
OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
fi
# Now convert the arguments - kludge to limit ourselves to /bin/sh
i=0
for arg in "$@" ; do
CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option
if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition
eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
else
eval `echo args$i`="\"$arg\""
fi
i=$((i+1))
done
case $i in
(0) set -- ;;
(1) set -- "$args0" ;;
(2) set -- "$args0" "$args1" ;;
(3) set -- "$args0" "$args1" "$args2" ;;
(4) set -- "$args0" "$args1" "$args2" "$args3" ;;
(5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
(6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
(7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
(8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
(9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
esac
fi
# Escape application args
save () {
for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
echo " "
}
APP_ARGS=$(save "$@")
# Collect all arguments for the java command, following the shell quoting and substitution rules
eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
cd "$(dirname "$0")"
fi
exec "$JAVACMD" "$@"

84
code_samples/action_basics/gradlew.bat vendored Normal file
View File

@ -0,0 +1,84 @@
@if "%DEBUG%" == "" @echo off
@rem ##########################################################################
@rem
@rem Gradle startup script for Windows
@rem
@rem ##########################################################################
@rem Set local scope for the variables with windows NT shell
if "%OS%"=="Windows_NT" setlocal
set DIRNAME=%~dp0
if "%DIRNAME%" == "" set DIRNAME=.
set APP_BASE_NAME=%~n0
set APP_HOME=%DIRNAME%
@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
set DEFAULT_JVM_OPTS=
@rem Find java.exe
if defined JAVA_HOME goto findJavaFromJavaHome
set JAVA_EXE=java.exe
%JAVA_EXE% -version >NUL 2>&1
if "%ERRORLEVEL%" == "0" goto init
echo.
echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
echo.
echo Please set the JAVA_HOME variable in your environment to match the
echo location of your Java installation.
goto fail
:findJavaFromJavaHome
set JAVA_HOME=%JAVA_HOME:"=%
set JAVA_EXE=%JAVA_HOME%/bin/java.exe
if exist "%JAVA_EXE%" goto init
echo.
echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
echo.
echo Please set the JAVA_HOME variable in your environment to match the
echo location of your Java installation.
goto fail
:init
@rem Get command-line arguments, handling Windows variants
if not "%OS%" == "Windows_NT" goto win9xME_args
:win9xME_args
@rem Slurp the command line arguments.
set CMD_LINE_ARGS=
set _SKIP=2
:win9xME_args_slurp
if "x%~1" == "x" goto execute
set CMD_LINE_ARGS=%*
:execute
@rem Setup the command line
set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
@rem Execute Gradle
"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
:end
@rem End local scope for the variables with windows NT shell
if "%ERRORLEVEL%"=="0" goto mainEnd
:fail
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
rem the _cmd.exe /c_ return code!
if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
exit /b 1
:mainEnd
if "%OS%"=="Windows_NT" endlocal
:omega

2
code_samples/action_basics/settings.gradle Normal file
View File

@ -0,0 +1,2 @@
rootProject.name = 'action_basics'

10
code_samples/action_basics/src/main/java/icons/ActionBasicsIcons.java Normal file
View File

@ -0,0 +1,10 @@
// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package icons;
import com.intellij.openapi.util.IconLoader;
import javax.swing.*;
public class ActionBasicsIcons {
public static final Icon Sdk_default_icon = IconLoader.getIcon("/icons/sdk_16.svg");
}

33
code_samples/action_basics/src/main/java/org/intellij/sdk/action/CustomDefaultActionGroup.java Normal file
View File

@ -0,0 +1,33 @@
// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package org.intellij.sdk.action;
import com.intellij.openapi.actionSystem.AnActionEvent;
import com.intellij.openapi.actionSystem.CommonDataKeys;
import com.intellij.openapi.actionSystem.DefaultActionGroup;
import com.intellij.openapi.editor.Editor;
import icons.ActionBasicsIcons;
/**
* Creates an action group to contain menu actions. See plugin.xml declarations.
* @author Anna Bulenkova
* @author jhake
*/
public class CustomDefaultActionGroup extends DefaultActionGroup {
/**
* Given CustomDefaultActionGroup is derived from ActionGroup, in this context
* update() determines whether the action group itself should be enabled or disabled.
* Requires an editor to be active in order to enable the group functionality.
* @see com.intellij.openapi.actionSystem.AnAction#update(AnActionEvent)
* @param event Event received when the associated group-id menu is chosen.
*/
@Override
public void update(AnActionEvent event) {
// Enable/disable depending on whether user is editing
Editor editor = event.getData(CommonDataKeys.EDITOR);
event.getPresentation().setEnabled(editor != null);
// Take this opportunity to set an icon for the menu entry.
event.getPresentation().setIcon(ActionBasicsIcons.Sdk_default_icon);
}
}

39
code_samples/action_basics/src/main/java/org/intellij/sdk/action/DynamicActionGroup.java Normal file
View File

@ -0,0 +1,39 @@
// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package org.intellij.sdk.action;
import com.intellij.openapi.actionSystem.ActionGroup;
import com.intellij.openapi.actionSystem.AnAction;
import com.intellij.openapi.actionSystem.AnActionEvent;
import icons.ActionBasicsIcons;
import org.jetbrains.annotations.NotNull;
/**
* Demonstrates adding an action group to a menu statically in plugin.xml, and then creating a menu item
* within the group at runtime. See plugin.xml for the declaration of DynamicActionGroup,
* and note the group declaration does not contain an action.
* DynamicActionGroup is based on ActionGroup because menu children are determined
* on rules other than just positional constraints.
*
* @author Anna Bulenkova
* @see ActionGroup
*/
public class DynamicActionGroup extends ActionGroup {
/**
* Returns an array of menu actions for the group.
*
* @param e Event received when the associated group-id menu is chosen.
* @return AnAction[] An instance of AnAction, in this case containing a single instance of the
* PopupDialogAction class.
*/
@NotNull
@Override
public AnAction[] getChildren(AnActionEvent e) {
return new AnAction[]{ new PopupDialogAction("Action Added at Runtime",
"Dynamic Action Demo",
ActionBasicsIcons.Sdk_default_icon)
};
}
}

78
code_samples/action_basics/src/main/java/org/intellij/sdk/action/PopupDialogAction.java Normal file
View File

@ -0,0 +1,78 @@
// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package org.intellij.sdk.action;
import com.intellij.openapi.actionSystem.AnAction;
import com.intellij.openapi.actionSystem.AnActionEvent;
import com.intellij.openapi.actionSystem.CommonDataKeys;
import com.intellij.openapi.project.Project;
import com.intellij.openapi.ui.Messages;
import com.intellij.pom.Navigatable;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import javax.swing.*;
/**
* Action class to demonstrate how to interact with the IntelliJ Platform.
* The only action this class performs is to provide the user with a popup dialog as feedback.
* Typically this class is instantiated by the IntelliJ Platform framework based on declarations
* in the plugin.xml file. But when added at runtime this class is instantiated by an action group.
*/
public class PopupDialogAction extends AnAction {
/**
* This default constructor is used by the IntelliJ Platform framework to
* instantiate this class based on plugin.xml declarations. Only needed in PopupDialogAction
* class because a second constructor is overridden.
* @see AnAction#AnAction()
*/
public PopupDialogAction() {
super();
}
/**
* This constructor is used to support dynamically added menu actions.
* It sets the text, description to be displayed for the menu item.
* Otherwise, the default AnAction constructor is used by the IntelliJ Platform.
* @param text The text to be displayed as a menu item.
* @param description The description of the menu item.
* @param icon The icon to be used with the menu item.
*/
public PopupDialogAction(@Nullable String text, @Nullable String description, @Nullable Icon icon) {
super(text, description, icon);
}
/**
* Gives the user feedback when the dynamic action menu is chosen.
* Pops a simple message dialog. See the psi_demo plugin for an
* example of how to use AnActionEvent to access data.
* @param event Event received when the associated menu item is chosen.
*/
@Override
public void actionPerformed(@NotNull AnActionEvent event) {
// Using the event, create and show a dialog
Project currentProject = event.getProject();
StringBuffer dlgMsg = new StringBuffer(event.getPresentation().getText() + " Selected!");
String dlgTitle = event.getPresentation().getDescription();
// If an element is selected in the editor, add info about it.
Navigatable nav = event.getData(CommonDataKeys.NAVIGATABLE);
if (nav != null) {
dlgMsg.append(String.format("\nSelected Element: %s", nav.toString()));
}
Messages.showMessageDialog(currentProject, dlgMsg.toString(), dlgTitle, Messages.getInformationIcon());
}
/**
* Determines whether this menu item is available for the current context.
* Requires a project to be open.
* @param e Event received when the associated group-id menu is chosen.
*/
@Override
public void update(AnActionEvent e) {
// Set the availability based on whether a project is open
Project project = e.getProject();
e.getPresentation().setEnabledAndVisible(project != null);
}
}

77
code_samples/action_basics/src/main/resources/META-INF/plugin.xml Normal file
View File

@ -0,0 +1,77 @@
<!-- Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
<idea-plugin>
<!-- Unique id for this plugin. Must stay constant for the life of the plugin. -->
<id>org.intellij.sdk.action</id>
<!-- Text to display as name on Preferences/Settings | Plugin page -->
<name>SDK: Action Sample Project</name>
<!-- The version of this plugin -->
<version>2.0.0</version>
<!-- Compatible with the following versions of IntelliJ Platform:
version 2018.3 (build #183) and newer. -->
<idea-version since-build="183"/>
<!-- Indicate this plugin can be loaded in all IntelliJ Platform-based products. -->
<depends>com.intellij.modules.platform</depends>
<!-- Text to display as description on Preferences/Settings | Plugin page -->
<description>
<![CDATA[
Demonstrates implementing Action and Action Group patterns.<br> Adds entries to the Tools menu.
]]>
</description>
<change-notes>
<![CDATA[
<ul>
<li><b>2.0.0</b> Renamed from register_actions and converted to Gradle project.</li>
<li><b>1.1</b> Refactor to give users feedback when menu items are selected.</li>
<li><b>1.0</b> Release 2018.3 and earlier.</li>
</ul>
]]>
</change-notes>
<!-- Text to display as company information on Preferences/Settings | Plugin page -->
<vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
<actions>
<!-- See https://www.jetbrains.org/intellij/sdk/docs/basics/action_system.html#registering-actions-in-pluginxml
for information about the elements and attributes used for actions and groups. -->
<!-- This <action> element adds a static menu item in first position of the Tools menu that shows PopupDialogAction. -->
<action id="org.intellij.sdk.action.PopupDialogAction" class="org.intellij.sdk.action.PopupDialogAction"
text="Pop Dialog Action" description="SDK Action Example" icon="ActionBasicsIcons.Sdk_default_icon">
<keyboard-shortcut first-keystroke="control alt A" second-keystroke="C" keymap="$default"/>
<mouse-shortcut keystroke="control button3 doubleClick" keymap="$default"/>
<add-to-group group-id="ToolsMenu" anchor="first"/>
</action>
<!-- All of the following menu groups add the action PopupDialogAction to menus in different ways.
Note that even though these groups reuse the same action class, in each use the action ids are unique. -->
<!-- GroupedActions demonstrates declaring an action group using the default ActionGroup implementation provided by the
IntelliJ Platform framework. (Note the lack of a group "class" attribute.) GroupedActions gets inserted after PopupDialogAction
in the Tools menu. Because the group's implementation is default, it cannot impose enable/disable conditions. Instead it
must rely on the conditions imposed by the parent menu where it is inserted. It declares one action in the group. -->
<group id="org.intellij.sdk.action.GroupedActions" text="Static Grouped Actions" popup="true" icon="ActionBasicsIcons.Sdk_default_icon">
<add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.intellij.sdk.action.PopupDialogAction"/>
<action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.GroupPopDialogAction"
text="A Group Action" description="SDK Static Grouped Action Example" icon="ActionBasicsIcons.Sdk_default_icon">
</action>
</group>
<!-- CustomDefaultActionGroup demonstrates declaring an action group based on a ActionGroup class supplied by this plugin.
This group is to be inserted atop the Editor Popup Menu. It declares one action in the group. -->
<group id="org.intellij.sdk.action.CustomDefaultActionGroup" class="org.intellij.sdk.action.CustomDefaultActionGroup" popup="true"
text="Popup Grouped Actions" description="Custom DefaultActionGroup Demo" icon="ActionBasicsIcons.Sdk_default_icon">
<add-to-group group-id="EditorPopupMenu" anchor="first"/>
<action class="org.intellij.sdk.action.PopupDialogAction" id="org.intellij.sdk.action.CustomGroupedAction"
text="A Popup Action" description="SDK Popup Grouped Action Example" icon="ActionBasicsIcons.Sdk_default_icon"/>
</group>
<!-- DynamicActionGroup demonstrates declaring an action group without a static action declaration.
An action is added to the group programmatically in the DynamicActionGroup implementation. -->
<group id="org.intellij.sdk.action.DynamicActionGroup" class="org.intellij.sdk.action.DynamicActionGroup" popup="true"
text="Dynamically Grouped Actions" description="SDK Dynamically Grouped Action Example" icon="ActionBasicsIcons.Sdk_default_icon">
<add-to-group group-id="ToolsMenu" anchor="after" relative-to-action="org.intellij.sdk.action.GroupedActions"/>
</group>
</actions>
</idea-plugin>

58
code_samples/action_basics/src/main/resources/META-INF/pluginIcon.svg Normal file
View File

@ -0,0 +1,58 @@
<svg xmlns="http://www.w3.org/2000/svg" width="81" height="80" viewBox="0 0 81 80">
<defs>
<linearGradient id="pluginsdk_80-a" x1="-.031%" x2="100.053%" y1="49.963%" y2="49.963%">
<stop offset="25.81%" stop-color="#F97A12"/>
<stop offset="45.91%" stop-color="#B07B58"/>
<stop offset="72.41%" stop-color="#577BAE"/>
<stop offset="91.05%" stop-color="#1E7CE5"/>
<stop offset="100%" stop-color="#087CFA"/>
</linearGradient>
<linearGradient id="pluginsdk_80-b" x1="27.55%" x2="82.223%" y1="34.514%" y2="77.605%">
<stop offset="0%" stop-color="#F97A12"/>
<stop offset="7.18%" stop-color="#CB7A3E"/>
<stop offset="15.41%" stop-color="#9E7B6A"/>
<stop offset="24.2%" stop-color="#757B91"/>
<stop offset="33.44%" stop-color="#537BB1"/>
<stop offset="43.24%" stop-color="#387CCC"/>
<stop offset="53.81%" stop-color="#237CE0"/>
<stop offset="65.52%" stop-color="#147CEF"/>
<stop offset="79.25%" stop-color="#0B7CF7"/>
<stop offset="100%" stop-color="#087CFA"/>
</linearGradient>
<linearGradient id="pluginsdk_80-c" x1="63.121%" x2="40.793%" y1="97.699%" y2="-6.587%">
<stop offset="0%" stop-color="#FE315D"/>
<stop offset="7.84%" stop-color="#CB417E"/>
<stop offset="16.01%" stop-color="#9E4E9B"/>
<stop offset="24.74%" stop-color="#755BB4"/>
<stop offset="33.92%" stop-color="#5365CA"/>
<stop offset="43.65%" stop-color="#386DDB"/>
<stop offset="54.14%" stop-color="#2374E9"/>
<stop offset="65.76%" stop-color="#1478F3"/>
<stop offset="79.4%" stop-color="#0B7BF8"/>
<stop offset="100%" stop-color="#087CFA"/>
</linearGradient>
<linearGradient id="pluginsdk_80-d" x1="25.331%" x2="93.854%" y1="24.119%" y2="132.621%">
<stop offset="0%" stop-color="#FE315D"/>
<stop offset="4.023%" stop-color="#F63462"/>
<stop offset="10.37%" stop-color="#DF3A71"/>
<stop offset="16.67%" stop-color="#C24383"/>
<stop offset="29.12%" stop-color="#AD4A91"/>
<stop offset="54.98%" stop-color="#755BB4"/>
<stop offset="91.75%" stop-color="#1D76ED"/>
<stop offset="100%" stop-color="#087CFA"/>
</linearGradient>
</defs>
<g fill="none" fill-rule="evenodd">
<g fill-rule="nonzero" transform="translate(8 8)">
<path fill="url(#pluginsdk_80-a)" d="M6.08754566,64 L2.66453526e-15,59.1000946 L0,26.7918961 L30,38.6703369 L10.1403967,64 L6.08754566,64 Z"/>
<path fill="url(#pluginsdk_80-b)" d="M20.9524706,64 L52.2740919,31.9159091 L37.6708832,0.460194805 L38.0580944,1.33226763e-15 L64,0 L64,64 L20.9524706,64 Z"/>
<path fill="url(#pluginsdk_80-c)" d="M34.4123783,0 L64,0 L64,28.0366227 L49.0078336,44 L34,0.44696173 L34.4123783,0 Z"/>
<path fill="url(#pluginsdk_80-d)" d="M30.3358775,64 L0,64 L0,49.9709549 L6.23437817,29.2830519 L0,27.1596093 L0,0 L39.4697238,0 L58,21.3844805 L30.5381317,63.9259091 L30.3358775,64 Z"/>
</g>
<g fill-rule="nonzero" transform="translate(12 12)">
<rect width="56" height="56" fill="#000"/>
<rect width="22" height="4" x="4" y="46" fill="#FFFEFE"/>
<path fill="#FFFEFE" d="M11.128,25.28 C8.584,25.28 6.016,24.392 4,22.592 L6.184,19.976 C7.696,21.224 9.28,22.016 11.2,22.016 C12.712,22.016 13.624,21.416 13.624,20.432 L13.624,20.384 C13.624,19.448 13.048,18.968 10.24,18.248 C6.856,17.384 4.672,16.448 4.672,13.112 L4.672,13.064 C4.672,10.016 7.12,8 10.552,8 C13,8 15.088,8.768 16.792,10.136 L14.872,12.92 C13.384,11.888 11.92,11.264 10.504,11.264 C9.088,11.264 8.344,11.912 8.344,12.728 L8.344,12.776 C8.344,13.88 9.064,14.24 11.968,14.984 C15.376,15.872 17.296,17.096 17.296,20.024 L17.296,20.072 C17.296,23.408 14.752,25.28 11.128,25.28 Z M19.512,25.04 L19.512,8.24 L26.064,8.24 C31.344,8.24 34.992,11.864 34.992,16.592 L34.992,16.64 C34.992,21.368 31.344,25.04 26.064,25.04 L19.512,25.04 Z M26.064,11.576 L23.208,11.576 L23.208,21.704 L26.064,21.704 C29.088,21.704 31.128,19.664 31.128,16.688 L31.128,16.64 C31.128,13.664 29.088,11.576 26.064,11.576 Z M37.28,25.04 L37.28,8.24 L40.976,8.24 L40.976,15.584 L47.744,8.24 L52.28,8.24 L45.416,15.368 L52.568,25.04 L48.128,25.04 L42.92,17.888 L40.976,19.904 L40.976,25.04 L37.28,25.04 Z"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.1 KiB

7
code_samples/action_basics/src/main/resources/icons/sdk_16.svg Normal file
View File

@ -0,0 +1,7 @@
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
<g fill="none" transform="translate(1 1)">
<rect width="14" height="14" fill="#000"/>
<rect width="5" height="1" x="1" y="11" fill="#FFFEFE"/>
<path fill="#FFFEFE" d="M1,5.96113281 L1.85546875,5.96113281 C1.89648438,6.30390625 2.2421875,6.52363281 2.74023438,6.52363281 C3.20019531,6.52363281 3.52539063,6.30097656 3.52539063,5.98164062 C3.52539063,5.71210937 3.31445313,5.55683594 2.79589844,5.44550781 L2.24511719,5.32832031 C1.47460938,5.1671875 1.09667969,4.76582031 1.09667969,4.12128906 C1.09667969,3.32441406 1.73828125,2.8 2.71386719,2.8 C3.64550781,2.8 4.3046875,3.32148437 4.33105469,4.07441406 L3.49902344,4.07441406 C3.45800781,3.74042969 3.14746094,3.51777344 2.71972656,3.51777344 C2.27734375,3.51777344 1.984375,3.72285156 1.984375,4.04511719 C1.984375,4.30585937 2.18652344,4.45527344 2.68164063,4.56074219 L3.19140625,4.66914062 C4.04101563,4.84785156 4.40722656,5.2140625 4.40722656,5.8703125 C4.40722656,6.72285156 3.75390625,7.24433594 2.69335938,7.24433594 C1.68554688,7.24433594 1.03222656,6.74921875 1,5.96113281 Z M5.19603365,2.90546875 L6.86009615,2.90546875 C8.11693209,2.90546875 8.84349459,3.6671875 8.84349459,4.99140625 C8.84349459,6.36542969 8.12572115,7.1359375 6.86009615,7.1359375 L5.19603365,7.1359375 L5.19603365,2.90546875 Z M6.08079927,3.66132812 L6.08079927,6.38007812 L6.71947115,6.38007812 C7.50169771,6.38007812 7.94115084,5.89960937 7.94115084,5.00605469 C7.94115084,4.15058594 7.48704927,3.66132812 6.71947115,3.66132812 L6.08079927,3.66132812 Z M10.5170673,7.1359375 L9.63230167,7.1359375 L9.63230167,2.90839844 L10.5170673,2.90839844 L10.5170673,4.7921875 L10.5698017,4.7921875 L12.1313251,2.90839844 L13.1157001,2.90839844 L11.5746845,4.76289062 L13.2240985,7.1359375 L12.1635517,7.1359375 L10.9360126,5.36640625 L10.5170673,5.86152344 L10.5170673,7.1359375 Z"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.9 KiB

4
code_samples/gradle_plugin_demo/build.gradle
View File

@ -1,3 +1,7 @@
plugins {
id "org.jetbrains.intellij" version "0.4.8"
}
sourceCompatibility = 1.8

53
intro/intellij_platform.md
View File

@ -2,44 +2,61 @@
title: What is the IntelliJ Platform?
---
The _IntelliJ Platform_ is not a product in and of itself, but provides a platform for building IDEs. It is used to power JetBrains products such as [IntelliJ IDEA](https://www.jetbrains.com/idea/), [WebStorm](https://www.jetbrains.com/webstorm/), [RubyMine](https://www.jetbrains.com/ruby/), [DataGrip](https://www.jetbrains.com/datagrip/) and [Rider](https://www.jetbrains.com/rider/). It is also Open Source, and can be used by third parties to build IDEs, such as [Android Studio](https://developer.android.com/studio/index.html) from Google.
The _IntelliJ Platform_ is not a product in and of itself but provides a platform for building IDEs. It is used to power JetBrains products such as [IntelliJ IDEA](https://www.jetbrains.com/idea/). It is also Open Source and can be used by third parties to build IDEs, such as [Android Studio](https://developer.android.com/studio/index.html) from Google.
The _IntelliJ Platform_ provides all of the infrastructure that these IDEs need to provide rich language tooling support. It provides a component driven, cross platform JVM based application host with a high level user interface toolkit for creating tool windows, tree views and lists (supporting fast search) as well as popup menus and dialogs.
The IntelliJ Platform provides all of the infrastructure that these IDEs need to provide rich language tooling support. It provides a component driven, cross-platform JVM based application host with a high-level user interface toolkit for creating tool windows, tree views and lists (supporting fast search) as well as popup menus and dialogs.
It also includes an image editor as well as a full text editor, and provides abstract implementations of syntax highlighting, code folding, code completion, and other rich text editing features.
Furthermore, it includes pluggable APIs to build common IDE functionality, such as a project model and a build system. It also provides infrastructure for a very rich debugging experience, with language agnostic advanced breakpoint support, call stacks, watch windows and expression evaluation.
Furthermore, it includes open APIs to build common IDE functionality, such as a project model and a build system. It also provides infrastructure for a very rich debugging experience, with language agnostic advanced breakpoint support, call stacks, watch windows, and expression evaluation.
But the _IntelliJ Platform_'s real power comes from the Program Structure Interface (PSI). This is a set of functionality that can be used to parse files and build rich syntactic and semantic models of the code, and to build indexes from this data. This powers a lot of functionality, from quick navigating to files, types and symbols, to the contents of code completion windows and find usages, code inspections and code rewriting, for quick fixes or refactorings, as well as many other features.
But the IntelliJ Platform's real power comes from the Program Structure Interface (PSI). This is a set of functionality that can be used to parse files and build rich syntactic and semantic models of the code, and to build indexes from this data. This powers a lot of functionality, from quick navigating to files, types and symbols, to the contents of code completion windows and find usages, code inspections and code rewriting, for quick fixes or refactorings, as well as many other features.
The IntelliJ Platform includes parsers and a PSI model for a number of languages, and its extensible nature means that it is possible to add support for other languages.
The _IntelliJ Platform_ includes parsers and a PSI model for a number of languages, and its composable nature means that it is possible to add support for other languages.
## Plugins
Products built on the _IntelliJ Platform_ are composable applications, with the platform being responsible for the creation of components, and the injection of dependencies into classes. The _IntelliJ Platform_ fully supports plugins, and JetBrains hosts a [plugin repository](https://plugins.jetbrains.com) that can be used to distribute plugins that support one or more of the products. It is also possible to host your own repositories, and distribute plugins separately.
Products built on the IntelliJ Platform are extensible applications, with the platform being responsible for the creation of components, and the injection of dependencies into classes. The IntelliJ Platform fully supports plugins, and JetBrains hosts a [plugin repository](https://plugins.jetbrains.com) that can be used to distribute plugins that support one or more of the products. It is also possible to host your own repositories, and distribute plugins separately.
Plugins can extend the platform in lots of ways, from adding a simple menu item to adding support for a complete language, build system and debugger. A lot of the existing functionality in the _IntelliJ Platform_ is written as plugins that can be included or excluded depending on the needs of the end product. See the section on [Plugins](/basics.md) for more details.
Plugins can extend the platform in lots of ways, from adding a simple menu item to adding support for a complete language, build system and debugger. A lot of the existing functionality in the IntelliJ Platform is written as plugins that can be included or excluded depending on the needs of the end product. See the [Quick Start Guide](/basics.md) for more details.
The _IntelliJ Platform_ is a JVM application, written mostly in Java and Kotlin. You should be familiar with these languages, and associated tooling, in order to write plugins for products based on the _IntelliJ Platform_. At this time, it's not possible to extend the _IntelliJ Platform_ in non-JVM languages.
The IntelliJ Platform is a JVM application, written mostly in Java and Kotlin. You should be experienced with these languages, large libraries written in them, their associated tooling, and large open source projects to write plugins for products based on the IntelliJ Platform. At this time, it's not possible to extend the IntelliJ Platform in non-JVM languages.
## Open Source
The _IntelliJ Platform_ is Open Source, under the [Apache license](upsource:///LICENSE.txt), and [hosted on GitHub](https://github.com/JetBrains/intellij-community).
The IntelliJ Platform is Open Source, under the [Apache license](upsource:///LICENSE.txt), and [hosted on GitHub](https://github.com/JetBrains/intellij-community).
While this guide refers to the _IntelliJ Platform_ as a separate entity, there is no "IntelliJ Platform" GitHub repo. Instead, the platform is considered to be an almost complete overlap with the IntelliJ IDEA Community Edition, which is a free and Open Source version of IntelliJ IDEA Ultimate (the GitHub repo linked above is the [JetBrains/intellij-community](https://github.com/JetBrains/intellij-community) repo).
While this guide refers to the IntelliJ Platform as a separate entity, there is no "IntelliJ Platform" GitHub repo. Instead, the platform is considered to be an almost complete overlap with the IntelliJ IDEA Community Edition, which is a free and Open Source version of IntelliJ IDEA Ultimate (the GitHub repo linked above is the [JetBrains/intellij-community](https://github.com/JetBrains/intellij-community) repo).
IntelliJ IDEA Ultimate is a superset of the IntelliJ IDEA Community Edition. It is based on the community edition, but includes closed source plugins ([see this feature comparison](https://www.jetbrains.com/idea/features/editions_comparison_matrix.html)). Similarly, other products such as WebStorm and DataGrip are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins.
The version of the IntelliJ Platform is defined by the version of the corresponding release of IntelliJ IDEA Community Edition.
For example, to build a plugin against IntelliJ IDEA (v2019.1.1,) build #191.6707.61, means specifying the same build number tag to get the correct Intellij Platform files from the `intellij-community` repo.
See the [build number ranges](/basics/getting_started/build_number_ranges.md) page for more information about build numbers corresponding to version numbering.
This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repo. This is what we call the _IntelliJ Platform_.
Typically, an IDE that is based on the IntelliJ Platform will include the `intellij-community` repo as a Git submodule and provide configuration to describe which plugins from the `intellij-community`, and which custom plugins will make up the product. This is how the IDEA Ultimate team work, and they contribute code to both the custom plugins and the IntelliJ Platform itself.
Typically, an IDE that is based on the _IntelliJ Platform_ will include the `intellij-community` repo as a Git submodule and provide configuration to describe which plugins from the `intellij-community`, and which custom plugins will make up the product. This is how the IDEA Ultimate team work, and they contribute code to both the custom plugins and the _IntelliJ Platform_ itself.
### IDEs Based on the IntelliJ Platform
The IntelliJ Platform underlies many JetBrains IDEs.
IntelliJ IDEA Ultimate is a superset of the IntelliJ IDEA Community Edition, but includes closed source plugins ([see this feature comparison](https://www.jetbrains.com/idea/features/editions_comparison_matrix.html)). Similarly, other products such as WebStorm and DataGrip are based on the IntelliJ IDEA Community Edition, but with a different set of plugins included and excluding other default plugins.
This allows plugins to target multiple products, as each product will include base functionality and a selection of plugins from the IntelliJ IDEA Community Edition repo.
Of course, because the _IntelliJ Platform_ is open source, we also accept [pull requests](https://github.com/JetBrains/intellij-community/pulls) to the platform itself, rather than just opening the source for view. Issue tracking is managed with [YouTrack (using the IDEA project)](https://youtrack.jetbrains.com/issues/IDEA), and if you wish to contribute to the platform, it is usually a good idea to open an issue describing the changes you wish to make before making the changes - this allows the team chance to give feedback and advice. More details can be found in the section on [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
The following IDEs are based on the IntelliJ Platform:
* JetBrains IDEs
* [AppCode](https://www.jetbrains.com/objc/)
* [CLion](https://www.jetbrains.com/clion/)
* [DataGrip](https://www.jetbrains.com/datagrip/)
* [GoLand](https://www.jetbrains.com/go/)
* [IntelliJ IDEA](https://www.jetbrains.com/idea/)
* [MPS](https://www.jetbrains.com/mps/)
* [PhpStorm](https://www.jetbrains.com/phpstorm/)
* [PyCharm](https://www.jetbrains.com/pycharm/)
* [RubyMine](https://www.jetbrains.com/ruby/)
* [WebStorm](https://www.jetbrains.com/webstorm/)
* [Android Studio](https://developer.android.com/studio/index.html) IDE from Google.
* [CUBA Studio](https://www.cuba-platform.com/)
## Rider
JetBrains [Rider](https://www.jetbrains.com/rider/) uses the IntelliJ Platform differently than other IntelliJ based IDEs. It uses the IntelliJ Platform to provide the user interface for a C# and .NET IDE, with the standard IntelliJ editors, tool windows, debugging experience and so on. It also integrates into the standard Find Usages and Search Everywhere UI, and makes use of code completion, syntax highlighting, and so on.
[Rider](https://www.jetbrains.com/rider/) uses the _IntelliJ Platform_ differently to other IntelliJ based IDEs. It uses the _IntelliJ Platform_ to provide the user interface for a C# and .NET IDE, with the standard IntelliJ editors, toolwindows, debugging experience and so on. It also integrates into the standard Find Usages and Search Everywhere UI, and makes use of code completion, syntax highlighting and so on.
However, it doesn't create a full PSI (syntactic and semantic) model for C# files. Instead, it reuses [ReSharper](https://www.jetbrains.com/resharper/) to provide language functionality. All of the C# PSI model, and all inspections and code rewriting, such as quick fixes and refactorings are run out of process, in a command line version of ReSharper. This means that creating a plugin for Rider involves two parts - a plugin that lives in the IntelliJ "front end" to show user interface, and a plugin that lives in the ReSharper "back end" to analyse and work with the C# PSI.
However, Rider doesn't create a full PSI (syntactic and semantic) model for C# files. Instead, it reuses [ReSharper](https://www.jetbrains.com/resharper/) to provide language functionality. All of the C# PSI model and all inspections and code rewriting, such as quick fixes and refactorings are run out of process, in a command line version of ReSharper. This means that creating a plugin for Rider involves two parts - a plugin that lives in the IntelliJ "front end" to show user interface, and a plugin that lives in the ReSharper "back end" to analyze and work with the C# PSI.
Fortunately, many plugins can simply work with the ReSharper backend - Rider takes care of displaying the results of inspections and code completion, and many plugins can be written that don't require an IntelliJ UI component. More details can be found in the Product Specific section.

24
intro/sdk_code_guidelines.md
View File

@ -31,7 +31,7 @@ Ultimately, the goal is to provide developers with roadmaps for implementing fun
Each roadmap should contain:
* Pointers to SDK documentation about the IntelliJ Platform APIs needed to implement the functionality.
* Pointers to relevant _basic_ SDK sample plugins.
* Pointers to relevant _advanced_ SDK sample plugins.
* Pointers to related _advanced_ SDK sample plugins.
## Naming Conventions for SDK Plugins
For _basic_ samples, the naming convention is focused on the IntelliJ Platform APIs being demonstrated.
@ -42,7 +42,9 @@ There is only one _basic_ sample per IntelliJ Platform API area.
For _advanced_ code samples, the name should reflect the complex functionality delivered by the plugin rather than the IntelliJ Platform APIs.
Advanced samples will be cross-referenced to the IntelliJ Platform APIs demonstrated in the sample.
Regardless of basic or advanced, an SDK plugin name is also known as the `Artifact ID` in the Gradle plugin wizard.
Note that the naming convention relates to the `Artifact ID`, which is the Gradle property `rootProject.name`.
This is different than the `<name>` definition provided in the [`plugin.xml`](#pluginxml-conventions) file.
See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for more information about the distinction.
## Plugin Copyright Statements
Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:
@ -52,11 +54,11 @@ Copyright 2000-$today.year JetBrains s.r.o. Use of this source code is governed
The copyright statement must appear in every source file with the `$today.year` [Velocity](https://www.jetbrains.com/help/idea/copyright-profiles.html) template resolved.
## Plugin ID Conventions
The plugin ID (`<id>` in `plugin.xml`) always begins with `org.intellij.sdk`.
The plugin ID is known as the `Group ID` in the Gradle plugin wizard.
The `Group ID` for SDK plugins is always `org.intellij.sdk`.
In general, the plugin ID is the `Group ID` concatenated with the `Artifact ID`.
For _basic_ code samples, it is not necessary to include "basic" in the plugin ID.
A plugin like `facet_basics` has the ID `org.intellij.sdk.facet`.
A plugin like `facet_basics` has the plugin ID `org.intellij.sdk.facet`.
## Plugin Package Names
Packages in plugins should begin with the plugin ID.
@ -64,7 +66,7 @@ If there is only one package in a plugin, then the package name is the same as t
## Plugin Directory Structure
SDK sample code should have a standard directory footprint.
Standardized structure not only makes the samples easier to navigate and understand, but it builds on the default Gradle plugin project structure.
Standardized structure not only makes the samples simpler to navigate and understand, but it builds on the default Gradle plugin project structure.
The following is the directory structure for a `foo_basics` plugin.
```text
code_samples/
@ -95,11 +97,13 @@ New SDK code samples should be developed [using Gradle](/tutorials/build_system.
As of this writing, the use of Gradle in SDK code samples still relies heavily on the `plugin.xml` for specifying the plugin configuration.
At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration.
The default contents of a `build.gradle` file are produced by the [Gradle project wizard](/tutorials/build_system/prerequisites.md#create-a-plugin-project-from-scratch).
The default contents of a `build.gradle` file are produced by the [New Project Wizard](/tutorials/build_system/prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard).
A consistent structure for an SDK code sample's `build.gradle` file is important for clarity and is based on the default produced by the project wizard.
Comments in SDK code sample `build.gradle` files should only draw attention to the parts of the Gradle configuration that are unique for a plugin.
For SDK code samples a few alterations are needed to the default build.gradle file produced by the plugin wizard:
For SDK code samples, a few alterations are needed to the default build.gradle file produced by the plugin wizard:
* Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`).
See the [Plugin Gradle Properties](/tutorials/build_system/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 statements to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section:
```groovy
// Prevents patching <idea-version> attributes in plugin.xml
@ -124,7 +128,7 @@ The sequence of elements in an SDK code sample `plugin.xml` file is:
* `<id>` Use the fully qualified [Plugin ID](#plugin-id-conventions).
* `<name>` The name value does not have to match the [Plugin Name](#naming-conventions-for-sdk-plugins).
It might reflect the functionality of the plugin.
The name must start with "SDK:".
The name must start with "SDK: ".
* `<version>` The code sample's version in MAJOR.MINOR.FIX format.
* MAJOR corresponds to a significant upgrade in functionality.
* MINOR corresponds to minor refactoring and small improvements in functionality.
@ -137,7 +141,7 @@ The sequence of elements in an SDK code sample `plugin.xml` file is:
Add this attribute if a plugin sample is deprecated with a release of the IntelliJ Platform.
* `<depends>` Include at least one dependency with the module `com.intellij.modules.platform` to indicate basic plugin compatibility with IntelliJ Platform-based products.
Add `<depends>` elements containing module FQNs as needed to describe more specialized [Compatibility with Multiple Products](/basics/getting_started/plugin_compatibility.md), and any other [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md).
* `<description>` is a succinct explanation of what is being demonstrated and how a user would access the functionality.
* `<description>` is a concise explanation of what is being demonstrated and how a user would access the functionality.
* `<change-notes>` is an ordered list by version numbers with a brief description of changes for each version.
* `<vendor>` Set the value to `IntelliJ Platform SDK`.
Set the attributes:

20
tutorials/build_system.md
View File

@ -3,12 +3,18 @@ title: Building plugins with Gradle
---
The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended solution for building IntelliJ plugins.
The plugin takes care of the dependencies of your plugin project - both the base IDE and the other plugins that your plugin may depend on.
It also provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains plugins repository](/plugin_repository/index.md).
To make sure that your plugin is not affected by [API changes](/reference_guide/api_changes_list.md) which may happen between major releases of the platform, you can easily build your plugin against many versions of the base IDE.
The plugin takes care of the dependencies of your plugin project - both the base IDE and other plugin dependencies.
It also provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains plugins repository](/plugin_repository/index.md).
To make sure that your plugin is not affected by [API changes](/reference_guide/api_changes_list.md) which may happen between major releases of the platform, you can easily build your plugin against many versions of the base IDE.
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
> **Note** Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`.
Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases).
The following tutorial refers to materials that can be found in the included [gradle_plugin_demo](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/gradle_plugin_demo) project.
Below are a series of guides to configuring Gradle support.
* [1. Getting Started](build_system/prerequisites.md)
* [2. Deploying a plugin](build_system/deployment.md)
Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins:
* [1. Getting Started with Gradle-Based Plugins](build_system/prerequisites.md)
* [2. Configuring Gradle-Based Plugins](build_system/gradle_guide.md)
* [3. Deploying a Plugin with Gradle](build_system/deployment.md)

2
tutorials/build_system/deployment.md
View File

@ -6,6 +6,8 @@ Once you have configured Gradle support, you can automatically build and deploy
To do so, you will need to have already published the plugin to the plugin repository.
For detailed information, please see the guide to [publishing a plugin](../../basics/getting_started/publishing_plugin.md).
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
### 2.0 Add your account credentials
In order to deploy a plugin to the plugin repository, you will first need to supply your JetBrains Account credentials.

159
tutorials/build_system/gradle_guide.md Normal file
View File

@ -0,0 +1,159 @@
---
title: Configuring Gradle for IntelliJ Platform Plugins
---
This page serves as a guide to Gradle-based plugin configuration for _IntelliJ Platform_ projects.
The IntelliJ IDEA Ultimate and Community editions bundle the Gradle and Plugin DevKit plugins to support Gradle-based development.
The [Getting Started with Gradle](prerequisites.md) page provides a tutorial for creating Gradle-based IntelliJ Platform plugins.
It may be useful to review the IntelliJ Platform page, particularly the description of versioning in the [Open Source](/intro/intellij_platform.md#open-source) section.
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
* bullet list
{:toc}
## Overview of the IntelliJ IDEA Gradle Plugin
The IntelliJ IDEA Gradle plugin is built from the open-source project `gradle-intellij-plugin`.
The plugin adds Gradle tasks for the `build.gradle` file that enable developing IntelliJ Platform plugins.
The [README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) file for the `gradle-intellij-plugin` project is the 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 IntelliJ IDEA Gradle plugin is listed.
* Also at the top is the minimum version of Gradle required to support the IntelliJ IDEA Gradle plugin.
* 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
This section presents a guided tour of Gradle plugin attributes to achieve commonly desired functionality.
### 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.
If a matching version of the specified IntelliJ Platform is not available on the local machine, the Gradle plugin downloads the correct version and type.
IntelliJ IDEA then indexes the build and any associated source code and JetBrains Java Runtime.
#### 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 build the plugin project.
If a local installation of IntelliJ IDEA 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.
#### 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.
Note that this attribute describes a dependency so the Gradle plugin can fetch the required artifacts.
The IntelliJ Platform plugin project is still required to declare these dependencies in its [Plugin Configuration](/basics/plugin_structure/plugin_configuration_file.md) (`plugin.xml`) file.
### 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.
Using the corresponding JetBrains Runtime is also the default, so for this use case no further configuration is required.
#### 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.ideaDirectory` will define an IDE to be used for the Development Instance in that single `runIde` task.
This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](/intro/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](/basics/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.
The Gradle plugin will fetch the specified JetBrains Runtime as needed.
### Managing Directories used by the Gradle Plugin
There are several attributes to control where the Gradle plugin places directories for downloads and for use by the IDE Development Instance.
The location of the [sandbox home](/basics/ide_development_instance.md#sandbox-home-location-for-gradle-based-plugin-projects) 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](/basics/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 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.
### 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.
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 IntelliJ IDEA Gradle plugin version, and the version of Gradle itself.
The Gradle plugin version is defined in the `plugins {}` section of a project's `build.gradle` file.
The Gradle version is in defined in a project's `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` ([Patching DSL](https://github.com/jetbrains/gradle-intellij-plugin#patching-dsl)) 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 `build.gradle` 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`.
* If one attribute is explicitly set (e.g. `patchPluginXml.sinceBuild`) and one is not (e.g. `patchPluginXml.untilBuild` has default value,) both attributes are patched at their respective (explicit and default) values.
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.
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.
As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](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 IntelliJ IDEA Gradle plugin does not combine and substitute those Gradle properties for the default `<id>` and `<name>` elements in the `plugin.xml` file.
### Publishing with the Gradle Plugin
Please review the [Publishing Plugins with Gradle](deployment.md) page before using the [Publishing DSL](https://github.com/jetbrains/gradle-intellij-plugin#publishing-dsl) attributes.
That documentation explains three different ways to use Gradle for plugin uploads without exposing account credentials.
## Common Gradle Plugin Configurations for Development
Different combinations of Gradle plugin attributes are needed to create the desired build or IDE Development Instance environment.
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.
This can be EAP (default) or determined from the [build number ranges](/basics/getting_started/build_number_ranges.md).
* If a production version of IntelliJ IDEA is the desired target, set the `intellij` [version attributes](#intellij-platform-configuration) 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 a different version or type of IntelliJ IDEA, set the [Running or Setup](#running-against-alternate-versions-and-types-of-intellij-platform-based-ides) DSL attributes accordingly.
For projects with only one `runIde` task, use the Running DSL attribute `runIde.ideaDirectory`.
* 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).
### Plugins Targeting Alternate IntelliJ Platform-Based IDEs
The Gradle plugin can also be configured for developing plugins to run in IDEs that are based on the IntelliJ Platform but are not IntelliJ IDEA.
This example focuses on the details of developing a plugin for PhpStorm.
It will be helpful to review the [PhpStorm Plugin Development](/products/phpstorm/phpstorm.md) section.
* The Gradle plugin attributes describing the configuration of the [IntelliJ Platform used to build the plugin project](#configuring-the-gradle-plugin-for-building-intellij-platform-plugin-projects) must be explicitly set.
The type will be "IC" because the IntelliJ Platform is defined by the IntelliJ IDEA Community Edition.
The BRANCH.BUILD number of the IntelliJ Platform (IntelliJ IDEA CE) is the same as for the PhpStorm target.
Although the FIX (tertiary) number may differ between the same versions of the applications, it won't affect the match of the IntelliJ Platform.
* All PhpStorm plugin projects have a dependency on the PhpStorm OpenAPI Library.
Any plugin targeting PhpStorm must list a dependency on the PHP plugin, and its version must be compatible with the target version of PhpStorm.
The plugin dependency must be declared using the Gradle plugin `intellij.plugins` attribute, which lists the `id` and `version` of the plugin dependency.
* The best practice is to use the target version of PhpStorm as the IDE Development Instance.
That enables running and debugging the plugin in the target (e.g., PhpStorm) application.
The choice of application to use for the IDE Development Instance is configured using the Gradle plugin attribute `intellij.alternativeIdePath`.
The snippet below is an example of configuring the Setup and Running DSLs in a `build.gradle` file to develop a plugin targeted at PhpStorm.
The configuration uses IntelliJ IDEA Community Edition v2019.1.2 (build 191.7141.44) as the IntelliJ Platform against which the plugin project is built.
It uses PhpStorm v2019.1.2 (build 191.7141.52) as the IDE Development Instance in which the plugin project is run and debugged.
```groovy
intellij {
// Define IntelliJ Platform against which to build the plugin project.
version '191.7141.44' // Same version (2019.1.2) as target PhpStorm
type 'IC' // Use IntelliJ IDEA CE as basis of IntelliJ Platform
// Require the Php plugin, must be compatible with target v2019.1.2
plugins 'com.jetbrains.php:191.6707.66'
}
runIde {
// Path to installed v2019.1.2 PhpStorm to use as IDE Development Instance
ideaDirectory '/Applications/apps/PhpStorm/ch-0/191.7141.52/PhpStorm.app/Contents'
}
```

38
tutorials/build_system/prerequisites.md
View File

@ -1,22 +1,17 @@
---
title: Getting Started with Gradle
---
<!--
// TODO:
1. Alexander's comments when available.
-->
Gradle is the preferred solution for creating IntelliJ Platform plugins.
The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based development.
These IntelliJ IDEA plugins are _Gradle_ and _Plugin DevKit_, which are enabled by default.
To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html).
> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
* bullet list
{:toc}
> **WARNING** When adding additional repositories to your Gradle build script, make sure to use HTTPS always.
## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard
IntelliJ IDEA supports creating new Gradle-based IntelliJ Platform plugin projects using the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle).
The Wizard creates all the necessary project files based on a few template inputs.
@ -39,12 +34,12 @@ On the first screen, the type of project is configured:
### Project Naming Screen
On this, the second screen of the Wizard, specify a [Group ID, Artifact ID, and plugin 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.
* _Group ID_ is typically a Java package name, and it is used for the `project.group` value in the project's `build.gradle` file.
* _Group ID_ is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's `build.gradle` file.
For this example, enter "com.your.company".
* _Artifact ID_ is the default name of the project JAR file (without version).
It is also used for the `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 `settings.gradle` file.
For this example, enter "my_gradle_plugin".
* _Version_ is used for the `project.version` value in the `build.gradle` file.
* _Version_ is used for the Gradle property `project.version` value in the `build.gradle` file.
For this example, enter "1.0".
Click _Next_ to continue.
@ -135,6 +130,13 @@ The New Project Wizard produces the `my_gradle_plugin` project `build.gradle` fi
}
```
#### Plugin Gradle Properties and Plugin Configuration File Elements
The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective `plugin.xml` elements `<name>` and `<id>`.
There is no IntelliJ Platform-related reason they should as they serve different functions.
The `<name>` element is often similar to the content root, but is more explanatory than the `rootProject.name`.
The `<id>` is a unique identifier over all plugins, typically a concatenation of the Maven `groupId` and `artifactId`; the default Gradle `project.group` property is only the `groupId`.
## Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin
Converting a DevKit-based 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.
@ -148,7 +150,7 @@ Converting a DevKit-based plugin project to a Gradle-based plugin project can be
* GroupID to the existing package in the initial source set.
* ArtifactID to the name of the existing plugin.
* Version to the same as the existing plugin.
* On the [Project Name and Location Screen](#project-project-name-and-location-screen) set the values to:
* On the [Project Name and Location Screen](#project-name-and-location-screen) set the values to:
* _Project name_ to the name of the existing plugin.
(It should be pre-filled from the _ArtifactID_)
* Set the _Project location_ to the directory of the existing plugin.
@ -197,17 +199,3 @@ Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-in
See the IntelliJ IDEA help for more information about [Working with Gradle tasks](https://www.jetbrains.com/help/idea/gradle.html#96bba6c3).
Finally, when `my_gradle_plugin` launches in the IDE development instance, there should be a new **Greeting** main menu to the right of the **Help** menu.
## Configuring a Gradle-Based IntelliJ Platform Plugin Project
See the [Gradle plugin README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#gradle) for more information about configuring IntelliJ Platform Plugin Projects.
> **Note** Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`.
Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases).
For example, to configure the **Sandbox Home** directory's location include the following in the project's `build.gradle` file:
```groovy
intellij {
sandboxDirectory = "$project.buildDir/myCustom-sandbox"
}
```
See the [IDE Development Instances](/basics/ide_development_instance.md) page for more information about default Sandbox Home directory locations and contents.