h2. Custom MPS Language
{toc:minLevel=3}
{anchor:introduction}
h3. Introduction
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.
{anchor:building custom mps for your project}
h3. 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.
!simple.project.png!
{anchor:creating custom mps build script using a wizard}
h4. 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.
!new.custom.build.script.png!
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].
!wizard.build.tools.png!
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}}.
!wizard.solution.png!
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}}.
!wizard.model.png!
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}}.
!wizard.modules.png!
After pressing {{"OK"}} button the wizard creates a build script.
!wizard.result.png!
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.
{anchor:running custom mps build script from mps}
h4. Running custom MPS build script from MPS
To run custom MPS build script use {{"Custom MPS Script"}} run configuration.
!custommps.runconfig.create.png!
!custommps.runconfig.edit.png!
You can also use a context menu item:
!custommps.runconfig.context.png!
{anchor:running custom mps build script manually}
h4. 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.
!custom.mps.generate.build.files.png!
The files are generated into a folder inside of build script base directory. In our case it's folder {{"build"}} in project base directory.
{noformat}
~/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
{noformat}
Here is the table with description of generated files.
|| File || Description ||
| help-build.xml | Script with different utility targets. |
| Info.plist | Configuration file for Mac OS X. |
| installer.nsi | Script for generating windows installer. |
| mps.bat | Windows startup file. |
| mps.sh | Unix startup file. |
| mps.vmoptions | File with java VM options. |
| \{YourProjectName\}-compile.xml | Compilation script. |
| \{YourProjectName\}-default-dist.xml | Main script, packaging MPS for different platforms. |
| \{YourProjectName\}-default.xml | Script for creating folder with MPS. |
| \{YourProjectName\}-languages.xml | Script for packaging modules into jars. |
| \{YourProjectName\}.properties | Properties file. |
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.
{noformat}
ant -f {YourProjectName}-default-dist.xml -Dmps_home={PathToMPS}
{noformat}
{anchor:build results}
h4. 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.
|| Artifact Name || Description ||
| MPS-\{build.numer\}.zip | Crossplatform build with bat and sh startup scripts. |
| MPS-\{build.numer\}-windows.exe | Windows installer (created only when running build script on windows). |
| MPS-\{build.numer\}-macos.zip | Zip for MacOsX. |
| MPS-\{build.numer\}-linux.tar.gz | Gzipped tar archive for Linux. |
Let's unpack MPS-\{build.numer\}.zip and see, what is inside it.
{noformat}
~/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
{noformat}
Here we see folders {{"simpleNamespace"}} and {{"SimpleProject"}}.
{noformat}
~/MPSProjects/SimpleProject/artifacts/MPS/simpleNamespace$ ls
jetbrains.mps.simple2.mpsarch.jar jetbrains.mps.simple3.mpsarch.jar
{noformat}
Folder {{"simpleNamespace"}} contains two packed languages {{jetbrains.mps.simple2}} and {{jetbrains.mps.simple3}}.
{noformat}
~/MPSProjects/SimpleProject/artifacts/MPS/SimpleProject$ ls
jetbrains.mps.simple1.mpsarch.jar
{noformat}
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.
!custom.libraries.png!
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.
!custom.mps.import.png!
Now we can create {{SimpleConcept1}} instance in a model.
!custom.mps.simple.concept.png!
...