Suggested doc fixes for building IntelliJ IDEA CE plugins
(I would happily submit a pull request for this if it's possible to do so.)
1) Googling how to create an IntelliJ plugin took me here. http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/setting_up_environment.html
The documentation there says "IntelliJ IDEA CE source code should be checked out to your local computer. This is not a requirement." At this point, the documentation is ambiguous about whether you only need to check out the source code or whether you also need to actually build it.
It turns out that you'll need to create the "IDEA jdk" SDK which is only documented on the "Check out and build" documentation.
This bullet:
"- IntelliJ IDEA CE source code should be checked out to your local computer. This is not a requirement but will make it much easier for you to debug your plugins. For detailed instructions, refer to Check Out And Build Community Edition."
Should be updated to say:
"IntelliJ IDEA CE source code should be checked out to your local computer, and you should run a local build. This is not a requirement but will make it much easier for you to debug your plugins; the documentation below assumes you have run a local build. For detailed instructions, refer to Check Out And Build Community Edition."
2) http://www.jetbrains.org/intellij/sdk/docs/basics/checkout_and_build_community.html recommends shallow-cloning the git repository with --depth 1, which implies --single-branch. That's a bad idea for Plugin developers, because they almost certainly want to switch to the branch/tag corresponding to their IDEA installation.
Doing a full clone doesn't take much longer than a shallow clone, but converting a shallow clone to a full clone requires a fair amount of git understanding. Naive users are likely to nuke and re-clone, when in fact they need to "git fetch --unshallow" (I'll bet most developers have never used --unshallow or heard of it.)
IMO the page should be updated to remove the suggestion to use "--depth 1", and should instead recommend running a full clone.
3) The build requires a Java 1.6 SDK. Those are not easy to come by on the latest macOS 10.12 Sierra. Oracle has never distributed a 1.6 JDK for OS X; Apple did it instead. Apple used to ship Java in the base OS X installation, but they stopped doing that years ago.
Today, you have to go to Apple to get a 1.6 JDK; their download page doesn't state clearly whether it's compatible with macOS Sierra.
Relying on Java 6 is not good, and is increasingly bad as the years go by. But, if we must use Java 6 for now, I think it would be helpful to provide a download link to Apple's JDK 6 https://support.apple.com/kb/dl1572?locale=en_US as well as Oracle's JDK download page for Windows and Linux. http://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase6-419409.html
Where the documentation says "pointing to an installation of JDK 1.6." I would add this emphasis:
"(Yes, it must be old JDK 1.6. Windows and Linux users can download JDK 6 from [Oracle]; macOS users can download Java 6 from [Apple]. Apple's old Java 6 download still works on the latest macOS Sierra.)"
4) The screenshot in this section shows Java 8, but that's wrong, because Java 6 is required.
5) "Unless you’re running on a Mac with an Apple JDK, add /lib/tools.jar"
This language is non-idiomatic in English. Instead say: "If you are running on Windows or Linux, add /lib/tools.jar to the set of IDEA jdk jars. (Apple JDK does not use/include a tools.jar, so please skip this step on macOS.)"
6) The screenshot in this section shows Java 8 on macOS. The screenshot should be on Windows or Linux, pointing to a Java 6 JDK.
7) Back in http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/setting_up_environment.html
After configuring the Plugin SDK, it recommends creating a new Module for your plugin. But at this point the user is presumably working in the IDEA project itself; we almost certainly don't want to create the plugin module there.
In addition, the very next page in this section is "Creating a Plugin Project" which is what the user should actually do, instead of creating a module.
I recommend deleting all of the bullets from "Select File | New | Module" on down.
I hope these suggestions are helpful! They certainly would have made life easier for me as I began working on my first IntelliJ plugin.
Please sign in to leave a comment.
Building your local Community Idea is absolutely not necessary, and I think that especially new user would be confused by this. Checking out the source code, on the other hand, is crucial because you need to browse the source code while you write your plugin code.
I think one or two additional sentences that you need the source code to attach it to your SDK so that you can inspect and debug your plugin code would be sufficient.
Checking out the source code is not enough. At the very least, something on the "setting up a development environment" page would need to explain how to create the (case sensitive) "IDEA jdk" using Java 6.
I suppose this could be done by substantially copying and pasting from the "check out and build" page, so users wouldn't need to build anything.
But users of the Plugin SDK must do almost every step of the CE build process except for "Build | Make Project" at the end. By the time you've gone as far as checking out the CE sources, switched to the right branch, switched the android sub-repos to the right branch, created the "IDEA jdk" SDK using Java 6, and created a normal "1.8" SDK using Java 8, literally all you have to do is ^F9 and you've done the build.
So IMO users might as well take that final step, if only to be sure that they've configured their JDKs correctly.
(Note that even if you disagree with my suggestion #1, all of the other numbered suggestions still apply.)
P.S. It would be great if IDEA could use a normal/modern JDK 8 instead, indeed I wish it could use the built-in JDK that comes with IDEA. Then, presumably, users could create a Plugin project right out of the box, without configuring any weird SDKs.
(It would be even better if IDEA CE could automatically clone the git repository and select the correct tag for the current release… but perhaps that's too much to ask.)
You don't need the (case sensitive) "IDEA jdk" if you are not building Idea itself. Just create a new "IntelliJ Plattform Plugin SDK" and set the Java SDK that is used to your 1.8 installation. Then, you attach your idea git folder as Sourcepath and you are done.
The Plugin setup guide says http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/setting_up_environment.html says "Select the IDEA jdk created in Check Out And Build Community Edition as the default Java SDK."
If that's wrong, and an ordinary 1.8 Java SDK can be used instead, then that one-line mistake just wasted hours of my time and should really be fixed.
But it seems like such a weird mistake to make that it seems like it must be on purpose…? There's even a screenshot and everything, where they explicitly select "IDEA jdk" instead of the 1.8 SDK right next to it.
Are you sure the doc is mistaken here?
Thanks for the feedback, passed on to the team. 1.6 JDK is needed only to build IDEA CE itself and is not needed to build your own plugins. This requirement is because of some sensitive compiler and runtime module parts that are used during compiling, running and debugging and must be fully compatible with very old Java versions.
It's also possible to build CE without Java 6 at all, but you will not be able to use it for development if your projects require older Java versions.
The docs need a review and update because the switch to Java 8 was relatively recent. Before that Java 6 was recommended for plugin development so that your plugins could run on Mac where Java 6 was used to run IDEA and was the only option for the very long time (until Java 8 became stable on this platform).
Since Java 8 runtime is now required for IDEA, you can build your own plugins with Java 8 without worrying that they will fail to load on Mac.
(Edit: Serge was faster)
I can only talk from experience. When I understood this correctly and you are only writing a plugin and you don't want to build Idea, then you can use a normal Java 8 installation as "internal" java of your "Plattform SDK". I believe the case-sensitive "IDEA jdk" (java 1.6) is necessary only for building Idea itself because some of the code still requires java 1.6.
The SDK setting of my plugin looks like this and works for ages
On the other hand, when I really want to build Idea (and not only my plugin), then I need the IDEA jdk set-up that is described there. Why don't you just try it out with your plugin?
Thanks for your input, http://www.jetbrains.org/intellij/sdk/docs/CONTRIBUTING.html has some details, we happily accept pull requests/patches or issues at https://youtrack.jetbrains.com/issues/IJSDK
My experience after attempting to rationalize everything in this conversation is as follows:
- Using Ultimate for my plugin project, but the plugin is against Community
- Java 8. Even after installing the old mac JDK 6, The Internal Java Platform selector will not allow me to choose it.
- When I run my plugin from the plugin project, the CE starts, and my plugin is installed -- but doesn't work.
- When I package the plugin into a jar and install it in with the plugin manager in CE, it works
I tried making the run configuration use the CE installation as its JRE, no change.
I tried making the run configuration use the old java 6. The configuration will not start (can't find the IDEA main class)
So yes, it appears to be true that you can just use java 8 to do your plugin development. But the developer experience is really bad because you can't run/debug your plugin from the project.
Issue 5 is very important. I missed that tools.jar file at the beginning and took me a lot of time to debug. Unfortunately, the latest document is still the bad version.