Building MPS language plugins
So you have created a set of languages and would like to make them available to the intended users. 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 MPS plugin.
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.
Starting point
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.
In brief:
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.
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 Solution wizard to generate a solution for us.
The wizard will ask whether the new build script should become a part of an existing solution or whether a new one should be created.
A model has to be created inside the new solution:
You can also specify, whether you intend to package the outcome as an MPS plugin or a standalone IDE:
Finally, you select the languages and solutions to include in the build srcipt:
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 Used languages and jetbrains.mps.ide.build should be mentioned as an Dependency.
With the solution and the model prepared you can now create a new build project through the pop-up menu:
Editing the build script
Either way you created the build script, now it is the time to edit your build description. In order to be able to package your languages and solutions as MPS plugins, you should untimately get a script similar to this one:
It is important to define artifact locations for all dependencies. The mps dependency, which is the only dependency in this build script, requires to know where to find the MPS application folder. You can keep using the default as long as you do not intend to run the build script from outside of MPS, since the current MPS instance is used by default
For more information about build language capabilities, refer to Build language.
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.mps property in the generated script. When running the script from the command line, we have to make it point to the location of the MPS application.
Since in the script above we set the locations of the artifact through a macro ($mps_home), we may set this property instead (necessary only if the locations on the build machine differ from the paths set in the build script).
Run Ant
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 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 location of the MPS application 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.mps="...". Since in our example above we use $mps_home to point to the MPS application, we can instead change the values of this property on the command line: ant -Dmps_home="path to the MPS application".
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 MPS plugins.
Pick the generated files and share them
Now we need to distribute the generated files to the MPS users so that they install the plugin that you have just created.
You can install the plugin either manually or through the MPS plugin manager. If installing manually, the downloaded plugin zip file must be unzipped into the MPS plugin folder.
Windows and Linux: typically USER_HOME/MPS_version/config/plugins or MPS_HOME/plugins
MacOS: ~/Library/Application Support/MPS_version/ or MPS_HOME/plugins
After restart the imported languages will become available in MPS.
Control visibility of modules in a plugin
By default, MPS assumes that all modules coming from language plugins should be visible to the end user. This is, however, not always the optimal strategy. With the number of languages growing and also with the complexity of the plugins rising, there are cases when the language designers want to hide certain modules from the end user. These modules will still be present and working, but the end user will not be shown these in the dialogs when selecting modules to import. This is useful in order not to confuse/overwhelm the end user with huge number of unrelated languages or solutions.
The plugins tell MPS about modules that they contribute by the means of the com.intellij.mps.LanguageLibrary extension point. Extensions to that extension point may provide an optional hide="true" attribute. This will make all modules of the plugin eligible to potential filtering. To enable filtering, a pattern must be specified using com.intellij.mps.VisibleModuleMask and the extension point that it defines.