So you have created a set of languages and would like to make them available to Java developers inside IntelliJ IDEA. In this document we are going to look at ways to package a set of languages, perhaps together with the runtimes they depend on, into a valid IntelliJ IDEA plugin.
Do you prefer video? Then you may also like to check out our screen-cast covering the topic of IntelliJ IDEA language plugin creation.
Note: The JavaExtensionsSample sample project that comes with MPS contains a fully functional build script to build and package the sample Java extensions into a plugin. You can take inspiration from there.
I assume you have built your languages and now it is the time share them with the world. There are a couple of steps that you need to follow in order to get a nice zip file, which you can upload to the server for others to grab.
- Create a build script (manually or through a wizard)
- Generate an Ant build xml file
- Run Ant
- Pick the generated files and share them
Now we'll continue in more detail. Alternatively you may like to try our new screen-casts that covers the topics of building as well as using IntelliJ IDEA language plugins.
Create a build script
First of all, we need to create a new build script in the newly created build solution. We have two options - using a wizard or creating the build description manually.
Using the Wizard
We can use the build script wizard to generate a script for us
The wizard will ask whether the new build project (script) should become a part of an existing solution or whether a new one should be created. You can also specify, whether you intend to package the outcome as an MPS or IntelliJ IDEA plugin:
If you have a plugin.xml file that describes the details of your plugin, it can also be used to fill-in the details of the build description that is being created. Otherwise you can still edit the plugin description manually later.
The generated build description script will look something like this:
The manual approach
To get more control over the process, we can alternatively create the build script ourselves. So first we will have to pick an existing solution or create a new one. In the root of your project's logical view right-click and pick "New Solution". Once the solution exists, create a new model in it. The model should have jetbrains.mps.build and jetbrains.mps.build.mps listed as its Imported languages and jetbrains.mps.ide.build should be an Imported model.
With the solution prepared you can now create a new build project through the pop-up menu:
Either way, now it is the time to edit your build description. In order to be able to package your languages and solutions as IntelliJ IDEA plugins, you should untimately get a script similar to this one:
It is important to define artifact locations for both dependencies. The IDEA dependency needs to know where to find an IntelliJ IDEA installation. The buildPlugin dependency requires to know where to find the MPS core IDEA plugin. After you enabled MPS inside IntelliJ IDEA by adding the plugin, it is typically located in the IntelliJ IDEA installation folder/plugins folder. Alternatively the plugin may also have been installed into the user home folder, under IntelliJ IDEA setting folder/config/plugins.
Please check out the build language documentation for details on the build language capabilities.
Generate an Ant build xml file
With the build script prepared you can now generate an Ant build.xml file. Just rebuild your build solution and the file will be generated into the location that you specified in the properties of your build script as indicated in the following picture:
The generated build.xml file should start something like this:
Notice the artifacts.IDEA and artifacts.buildPlugin properties in the generated script. When running the script from the command line, we have to make them point to the IntelliJ IDEA installation and the location of the MPS core plugin respectively.
Since in the script above we set the locations of both artifacts through macros ($idea_home and $plugins_home), we may set theese properties instead (necessary only if the locations on the build machine differ from the paths set in the build script).
Time to run the build and get our plugin. Again, we have two choices - either stay inside MPS or use the command line.
From within MPS
Just right-click on the build node in the Project View and choose run:
The generated artifacts will be located in the build folder inside the folder you specified as the base.
From the command line
You need to navigate the command line to the folder where the build.xml file is located and run ant. If the locations of the MPS core plugin and IntelliJ IDEA on the build machine are different from the path set in the build script, we should specify the actual location on the command line ant -Dartifacts.buildPlugin="..." -Dartifacts.IDEA="...". Since in our example above we use $idea_home to point to the IntelliJ IDEA installation folder and $plugins_home to point to the MPS core plugin, we can instead change the values of theese properties on the command line: ant -Didea_home="path to idea" -Dplugins_home="path to the MPS core plugin".
This step, no matter whether you run the script from MPS or the command line, will generate a zip file containing all the necessary jar files organized as we specified in the layout section of our build script or (as in our displayed case) using the default layout of IntelliJ IDEA plugins.
Pick the generated files and share them
Now we need to distribute the generated files to the IntelliJ IDEA users so that they can add them as plugins. Check out Using MPS inside IntelliJ IDEA for detailed instructions on how to install the plugin for use in IntelliJ IDEA.