Custom MPS Language

Custom MPS Language

The purpose of custom MPS language is to allow a programmer to create MPS distribution containing his own languages, so that users would be able to use those languages straight away.

The language adds two constructions into packaging language: mps-build and library. library is a special folder inside of MPS build, where packaged modules are located. While building MPS, a special configuration file is created and added to the build where all library folders are listed, so MPS will know, where to look for modules.

Building custom MPS for your project

In this section we will build a custom MPS distribution for a sample project. Our project will have three simple languages.

Creating custom MPS build script using a wizard

To create a custom MPS build script for the project, select "New" -> "Custom MPS Build Script" from project popup menu.

This action starts a wizard. The first step is to select a location of special zip file, MPS-buildTools.zip, containing files required to build MPS. This file can be downloaded from http://jetbrains.com/mps/download.

Next, the wizard asks to select, whether a new solution would be created for a build script, or an old one should be picked. For this example we select to create a solution named SimpleProject.build.

The next step is to choose a model for a build script. If we selected an existing solution on previous step, we could use one of the models in that solution. But as we create a new solution for our build script, we have only one option: to create a new model. Let's call the new model SimpleProject.build.

The last step is to select modules, included in build. Let's select all languages in project and exclude a solution jetbrains.mps.simple1.sandbox.

After pressing "OK" button the wizard creates a build script.

As you can see, resulting script has two libraries: simplenamespace library for modules in a namespace simpleNamespace and simpleproject library for modules with empty namespace.

Running custom MPS build script from MPS

To run custom MPS build script select the action "Build Custom MPS" from script's popup menu.

The action generates files from build script and runs it inside MPS. You will see a tool window "Build Custom MPS" with build results.

Running custom MPS build script manually

To run custom MPS script by hands you should generate build files by selecting "Generate Build Files" action from model's popup menu.

The files are generated into a folder inside of build script base directory. In our case it's folder "build" in project base directory.

~/MPSProjects/SimpleProject/build$ ls
help-build.xml  installer.nsi  mps.sh         SimpleProject-compile.xml       SimpleProject-default.xml    SimpleProject.properties
Info.plist      mps.bat        mps.vmoptions  SimpleProject-default-dist.xml  SimpleProject-languages.xml

Here is the table with description of generated files.

To start custom MPS build you should use {YourProjectName}-default-dist.xml file (in our case it's SimpleProject-default-dist.xml). It requires mps_home property to be set to the directory, containing MPS. To run build from console you can use the following command.

ant -f {YourProjectName}-default-dist.xml -Dmps_home={PathToMPS}

Build results

Custom MPS build script creates folder "artifacts" in script base directory (in our case it's project home directory) with MPS build for different platforms. They all are marked with number of MPS build used when running build script.

Let's unpack MPS-{build.numer}.zip and see, what is inside it.

~/MPSProjects/SimpleProject/artifacts/MPS$ ls
about.txt  build.number  entryPoints.xml  license  mps.sh    plugin   readme.mps.txt  samples.zip      SimpleProject
bin        core          lib              mps.bat  platform  plugins  readme.txt      simpleNamespace  workbench

Here we see folders "simpleNamespace" and "SimpleProject".

~/MPSProjects/SimpleProject/artifacts/MPS/simpleNamespace$ ls
jetbrains.mps.simple2.mpsarch.jar  jetbrains.mps.simple3.mpsarch.jar

Folder "simpleNamespace" contains two packed languages jetbrains.mps.simple2 and jetbrains.mps.simple3.

~/MPSProjects/SimpleProject/artifacts/MPS/SimpleProject$ ls
jetbrains.mps.simple1.mpsarch.jar

Folder "SimpleProject" contains packed language jetbrains.mps.simple1.

Let's start MPS to make sure that those languages are available in it. Select "File" -> "Settings" -> "Ide Settings" -> "MPS Library Manager". You can see, that there are new simplenamespace and simpleproject libraries pointing to "simpleNamespace" and "SimpleProject" directories respectively.

Let's create a test project and try to write something on jetbrains.mps.simple1 language. Let's create a solution "Test.sandbox" with a model "Test.sandbox.sandbox" and import
jetbrains.mps.simple1 into it. All three languages we wanted to pack are loaded by MPS and available for import.

Now we can create SimpleConcept1 instance in a model.