In the following, we provide some brief instructions on how to get started with PEoPL. If you have any further questions please do not hesitate to contact us. Feedback, comments and hints to improve this tutorial are highly appreciated.
MPS uses a projectional editor, which is quite different to what we know from editing text. The following links may help you getting started with MPS.
There are two different versions of PEoPL. First, an old, yet full-fledged version leveraging a modified MPS. Second, PEoPL with advanced support for adding variability to arbitrary languages (without modifying MPS itself).
All information needed to install the new version can be found on github.
We currently only provide a modified MPS version together with a PEoPL plugin bundle (i.e., you cannot use the original standalone of MPS provided by JetBrains). Sources can be found at github.
- PEoPL-0.6 (modified MPS 3.3.6): Mac OS X, Linux, Windows
- PEoPL-0.6.15, platform-independent plugin-bundle
- Cheat sheet (shortcuts)
- Examples: EmtpyStack, GPL, STE, Jest
Quick PEoPL Guide
Installing the PEoPL plugin bundle
After opening the standalone, you’ll be greeted by a welcome screen.
Please navigate to the MPS preferences (may differ on Windows and Linux machines).
Next, navigate to Plugins and click Install plugin from disk…
Select and install the three plugins provided with the bundle in the following order: peoplMbeddrPluginsBundle.zip, peoplCore.zip, peoplBaseLanguageExtension.zip
Now you are all set and ready to explore PEoPL. Next, you can either create a new project or open an existing one.
Creating a project
You can create a new empty project from the welcome screen.
You have two choices: write a new product line from scratch (1) or import existing source code to featurize it (2). Either way, you need a PEoPL-Solution. Right-click on the top node of the project tree and select New -> Peopl Solution.
This action creates a new Solution containing two models in it, peoplConfig and sandbox. You can think of a model as a Java package. The model peoplConfig holds a ModuleDefinition in which you define your Modules. Moreover, there is a ModuleConfiguration in which you create your algebraic expressions for product variant generation.
Writing product lines from scratch
We use the sandbox model to implement new Java classes. In particular, you need to use PEoPL’s class container for Java classes instead of the class concept provided by JetBrains. A class container can hold 1…n alternative Java classes, each of which can be used like a normal class.
Importing existing source code
Unfortunately, it is not possible to import product lines written with other languages and tools, yet. Thus, we can only import existing Java sources.
Importing existing code is a bit different. You need to right-click at your solution and choose New -> Models from Java Sources on your solution. Then you can select your Java sources. Note that all of your sources need to be in a Java package! If any class is not assigned to a Java package, the import will fail.
As you can see, the model indicates that there are some errors, which need a workaround.
This issue arises, because some dependencies have not been set automatically during import. As an example, we take the class Vertex. You can see that some dependencies on data types have not been resolved.
Luckily, the type checker, that comes with MPS, can resolve most of these errors (right-click on the Solution and choose Check Solution).
Next, a tool window pops up. You can press Perform Quick Fixes.
After you have fixed the errors, it’s time to convert the imported classes into the PEoPL format.
After converting the Solution, your code should look like this. In particular, PEoPL converts the conventional Java classes into class containers. PEoPL opens class containers using the standard editors defined in PEoPL’s core. There, feature code is indicated by square brackets.
Exploring the product line
We implemented a set of projectional editors to be able to explore class containers in the context of JetBrains base language (a model of Java) in a more convenient way.
You can open these editors using editor hints, a mechanism in MPS to switch editor appearance of AST elements.
In particular, we implemented annotative, product and FOP-like editors. The first two can be activated using the hints menu. Note that FOP-like editors can only be opened from the corresponding project explorer (not shown below). For conveniently switching editors, we also provide some shortcuts:
- Standard annotative editor (cmd+alt+1)
- Standard annotative editor with hidden module information and variation point information (cmd+alt+2)
- Colored product variant editor (cmd+alt+3)
- Product variant editor (cmd+alt+4)
Below, we show the standard annotative editor.
Next, we use these editors (i.e., projections of the variational AST) to implement features through corresponding modules.
To assign a module to an AST node, we hit the MPS shortcut alt+enter, which opens a so-called Intentions menu. Intentions allow executing AST changes and more. In the example, we are about to assign a module to the InstanceMethodDeclaration called getNeighbors().
In particular, applying the intention allows to choose a module. This module in turn assigns a fragment (i.e., the one containing getNeighbors()) to a variation point.
It is likely that you need more modules than just Base. We can define new modules in the ModuleDefinitions node in the peoplConfig model.
To produce a product variant, you can use three operators (+, -, ->) in the Module configuration. The operator “+“ allows to add feature details, while “–” is used for removal and “->” for overriding. You can play with the operators and see results using the product projection (cmd+alt+3). A detailed explanation can be found in our ACM SAC paper “Integrating Feature-based Implementation Approaches using a Common Graph-based Representation“.
Please let us know, if you have any questions related to PEoPL or this tutorial.