- Contributing to Flutter Plugin for IntelliJ
We gladly accept contributions via GitHub pull requests! If you are new to codiing IntelliJ plugins, here are a couple links to get started:
You must complete the Contributor License Agreement before any of your contributions with code get merged into the repo. If you've never submitted code before, you must add your (or your organization's) name and contact info to the AUTHORS file.
- Install Flutter SDK from Flutter SDK download or GitHub and set it up according to its instructions.
- Verify installation from the command line:
- Connect an android device with USB debugging.
cd path/to/flutter/examples/hello_world
flutter pub get
flutter doctor
flutter run
- Fork
https://github.com/flutter/flutter-intellij
into your own GitHub account. If you already have a fork, and are now installing a development environment on a new machine, make sure you've updated your fork with the master branch so that you don't use stale configuration options from long ago. git clone -c core.symlinks=true https://github.com/<your_name_here>/flutter-intellij
cd flutter-intellij
git remote add upstream https://github.com/flutter/flutter-intellij
The nameupsteram
can be whatever you want.
The current Java Developmenet Kit version is: 20.
- Set your
JAVA_HOME
directory in your environment.- For example, on macOS, the following works:
Check what version of java you have:
Set your
/usr/libexec/java_home -V
JAVA_HOME
env variable to match that version.export JAVA_HOME=`/usr/libexec/java_home -v 20`
- For example, on macOS, the following works:
Check what version of java you have:
- Set your
FLUTTER_SDK
directory to point to/path/to/flutter
. - Also set your
DART_SDK
directory to/path/to/flutter/bin/cache/dart-sdk
. - Ensure both
DART_SDK
,FLUTTER_SDK
andJAVA_HOME
are added to thePATH
in the shell initialization script that runs at login. (not just for the one used for every interactive shell).export PATH=$DART_SDK/bin:$FLUTTER_SDK/bin:$JAVA_HOME/bin:$PATH
- Make sure you're using the latest stable release of IntelliJ,
or sownload and install the latest version of IntelliJ (2023.1 or later).
- IntelliJ Downloads
- Either the community edition (free) or Ultimate will work.
- Determine the directory of your downloaded IntelliJ IDEA installation. e.g.
IntelliJ IDEA CE.app
(macOS)~/Library/Application Support/JetBrains/Toolbox/apps/IDEA-U/ch-0/231.8109.175/IntelliJ IDEA.app
(macOS)~/idea-IC-231.8109.175
(Linux)X:\path\to\your\IDEA-U\ch-0\231.8109.175
(Windows after installed)
- Start the IntelliJ IDEA with the
flutter-intellij
project. If you see a popup with "Gradle build scripts found", confirm loading the Gradle project, and wait until syncing is done. If you didn't see the popup at the first start, delete & re-clone the repo and try again.- Ignore suggestion for
protobuf-java
plugin, unless you want it.
- Ignore suggestion for
- Prepare other dependencies from the command line:
cd path/to/flutter-intellij
dart pub get
(cd tool/plugin; dart pub get)
bin/plugin test
- In the "Project Structure" dialog (
File | Project Structure
):- Select "Platform Settings > SDKs", click the "+" sign at the top "Add New SDK (Alt+Insert)",
then select "Add JDK...".
- Point it to the directory of the jbr which is under the IDEA's content (e.g.
IntelliJ IDEA CE.app/Contents/jbr
). - Change the name to
IDEA JBR 17
(or any names that your can easily identify).
- Point it to the directory of the jbr which is under the IDEA's content (e.g.
- Select "Platform Settings > SDKs", click the "+" sign at the top "Add New SDK (Alt+Insert)",
then select "Add IntelliJ Platform Plugin SDK...".
- Point it to the directory of the content which is under the IDEA's installation.
- Remember the generated name (probably
IntelliJ IDEA IU-231.8109.175
) or change to name to format like this. - Change the "Internal Java Platform" to the previous
IDEA JBR 17
.
- Select "Platform Settings > Project", change the "SDK" selection to the previous IntelliJ Platform Plugin SDK
(probably
IntelliJ IDEA IU-231.8109.175 java version 17
). - Select "Platform Settings > Modules".
- Select "flutter-intellij > flutter-idea > main" module, switch to the "Paths" window, select the Inherit project compile output path option then apply. This step can be repeated after everytime the project is open.
- Select every module from the top (flutter-intellij) to the bottom (test) (could be 6 modules in summary),
switch to the "Dependencies" window, change the "Module SDK" selection to
Project SDK
.
- Select "Platform Settings > SDKs", click the "+" sign at the top "Add New SDK (Alt+Insert)",
then select "Add JDK...".
- In the "File | Settings | Build, Execution, Deployment | Build Tools | Gradle" setting:
- Change "Gradle JVM" selection to "Project SDK".
- In the "File | Settings | Build, Execution, Deployment | Compiler" setting:
- In "Java Compiler", change the "Project bytecode version" to the same version of the JDK.
- In "Kotlin Compiler", change the "Target JVM version" to the same version of the JDK.
- One-time Dart plugin install - first-time a new IDE is installed and run you will need to install the Dart plugin.
- Find
Plugins
(in "File | Settings | Plugins") and install the Dart plugin, then restart the IDE if needed.
- Find
- Build the project using
Build
|Build Project
. - Try running the plugin; select the
flutter-intellij [runIde]
run config then click the Debug icon. This should open the "runtime workbench", a new instance of IntelliJ IDEA with the plugin installed. - If the Flutter Plugin doesn't load (Dart code or files are unknown) see above "One-time Dart plugin install".
- Verify installation of the Flutter plugin:
- Select
flutter-intellij [runIde]
in the Run Configuration drop-down list. - Click Debug button (to the right of that drop-down).
- In the new IntelliJ process that spawns, open the
path/to/flutter/examples/hello_world
project. - Choose
Edit Configurations...
in the Run Configuration drop-down list. - Expand
Edit configuration templates...
and verify that Flutter is present. - Click [+] and verify that Flutter is present.
- Select
If exceptions like these occurred:
A problem occurred configuring project ':flutter-idea'.
> Source directory 'X:\path\to\your\flutter-intellij\flutter-idea\resources' is not a directory.
Check out if the directory is a symlink by open the link in IDEA, and it'll display as:
../resources
Delete the file, then re-clone the repo using the below command:
git clone -c core.symlinks=true https://github.com/<your_name_here>/flutter-intellij
NOTE: Avoid symlinks addition during development as possible as you can, since they can lead to various of file-based issues during the development.
This is not currently required. However, for debugging unit tests it may be handy; please ignore for now.
The Gradle build script currently assumes that some dependencies are present in the artifacts
directory.
This project uses an External Tool in IntelliJ to ensure the dependencies are present.
It appears that external tools are not shareable.
To make one, open the "Run Configuration" dialog and select "Flutter Plugin".
Look at the "Before launch" panel. It probably displays an Unknown External Tool.
Double-click that, then click edit icon in the new panel (pencil).
Set the name to "Provision". Set the values:
- Program: /bin/bash
- Arguments: bin/plugin test -s
- Working directory:
$ProjectFileDir$ - You can select that from a list by clicking the "+" symbol in the field
There is a screenshot of this dialog in resources/intellij/Provision.png
.
Save, close, and re-open the "Run Configuration" dialog. Confirm that the External Tool is named "Provision".
If you know where the Application Support files are located for your version of IntelliJ,
you can drop the definition into its tools
directory before starting IntelliJ.
The definition is in resources/intellij/External Tools.xml
.
[Note: this may be out-of-date. It has not been verified recently.]
The repository contains two pre-defined test run configurations. One is for "unit" tests; that is currently defined as tests that do not rely on the IntelliJ UI APIs. The other is for "integration" tests - tests that do use the IntelliJ UI APIs. The integration tests are larger, long-running tests that exercise app use cases.
In order to be able to debug a single test class or test method you need to do the following:
- Open the test source file in the editor. Navigate to
flutter-idea/testSrc/unit/...
to open it. - Tests must run using Gradle, so be sure to open the source from the Gradle module.
- Find the test you want to run. Right-click the green triangle next to the test name and choose
Debug <test-name>
.
The test configuration can be tricky due to IntelliJ platform versioning. The plugin tool (below) can be a more reliable way to run tests.
To run unit tests on the command line:
bin/plugin test
See TestCommand
in tool/plugin/lib/plugin.dart
for more options.
It is also possible to run tests directly with Gradle, which would allow passing more command-line arguments:
./gradlew test
If you wanted to run a subset of the tests you could do so this way. See the Gradle docs for more info about testing. However, you must have run the tests once using the plugin tool, to ensure all the dependencies have been configured.
Sometimes browsing the source code of IntelliJ is helpful for understanding platform details that aren't documented.
- In order to have the platform sources handy, clone the IntelliJ IDEA Community Edition repo
(
git clone https://github.com/JetBrains/intellij-community
) - Sync it to the same version of IntelliJ as given by
baseVersion
in gradle.properties (git checkout 211.7628
). It will be in "detached HEAD" mode. - Open the Project Structure dialog (
File > Project Structure
). In theIntelliJ IDEA Community Edition
sdk, head over to theSourcepaths
tab and add the path tointellij-community
. Accept all the root folders found by the IDE after scanning. - Do the same for the intellij-plugins repo to get Dart plugin sources. Sync to the same version as before.
Android Studio cannot use the Gradle-based project definition,
so it still needs the flutter-intellij-community.iml
file.
Obviously, unit tests can only be run from the command line.
- Initialize Android Studio sources.
- Checkout Flutter plugin sources, tip of tree.
- Follow the directions for setting up the Dart plugin sources in
intellij-plugins/Dart/README.md
with these changes:- you do not need to clone the intellij-community repo
- open studio-main/tools/adt/idea in IntelliJ
- possibly skip running
intellij-community/getPlugins.sh
- Checkout Dart plugin sources.
- Using the Project Structure editor, import
- intellij-plugins/Dart/Dart-community.iml (if there are lots of errors, see step 7)
- flutter-intellij/flutter-intellij-community.iml
- Using the Project Structure editor, expand the tree to show
intellij > android > adt > ui
. Select theui
module then add a module dependency from it toflutter-intellij-community
. Also add a dependency on the Dart module unless using step 7. - (Optional, when Dart sources are not usable.) Make sure the
flutter-intellij-community
module has a dependency on a library namedDart
. It should be pre-defined, but if it is out-of-date then adjust it to point toflutter-intellij/third_party/lib/dart-plugin/xxx.yyyy/Dart.jar
. Delete the Dart module from the Project Structure modules list.
We use JxBrowser, a commercial product, to embed DevTools within IntelliJ. A license key is required to use this feature in development, but it is not required for developing unrelated (most) features.
Getting a key to develop JxBrowser features:
- Internal contributors: Ask another internal contributor to give you access to the key.
- External contributors: Our license key cannot be transferred externally, but you can acquire your own trial or regular license from TeamDev to use here.
To set up the license key:
- Copy the template at resources/jxbrowser/jxbrowser.properties.template and save it as resources/jxbrowser/jxbrowser.properties.
- Replace
<KEY>
with the actual key.
We require that all commits to the repository are signed with GPG or SSH, see GitHub's documentation.
If you are on macOS, and choose to sign with GPG, here are some additonal notes:
- Download GPG's tarball along with its dependencies from here. GPG is the first item, the dependencies are in the block below (Libgpg-error, Libgcrypt, etc.).
- To install these tarballs on macOS, follow these instructions:
- Download the desired
.tar.gz
or (.tar.bz2
) file - Open Terminal
- Extract the
.tar.gz
or (.tar.bz2
) file with the following commands (Follow these steps for the dependencies first, then for GPG):
tar xvjf PACKAGENAME.tar.bz2 # Navigate to the extracted folder using cd command cd PACKAGENAME # Now run the following command to install the tarball ./configure make sudo make install
- Download the desired
- You may need to install pinentry (
brew install pinentry
) - If the Pinentry continues to not work, check its path (
which pinentry
) and add it to the file~/.gnupg/gpg-agent.conf
, i.e.:pinentry-program /path/to/pinentry
- You may need to set the tty
export GPG_TTY=$(tty)
if you get this error when trying to commit:error: gpg failed to sign the data fatal: failed to write commit object