Install & Explore

Overview

In the following, we provide some brief instructions on how to install and use 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.

Note: PEoPL is a novel instantiation of JetBrains Meta Programming System (MPS). In other words, we modified the MPS sources to support product line development. Thus, you cannot use the original standalone of MPS provided by JetBrains. Moreover, we use several language extensions provided with mbeddr, an instantiation of MPS for embedded software development.

MPS

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.

Downloads

Note: We currently only provide a modified MPS version together with a PEoPL plugin bundle. We plan to take the github-page of PEoPL public as soon as possible. For now, please contact us, if you need full access to the sources.

Quick PEoPL Guide

After you downloaded our modified MPS version, you need to install the PEoPL plugin bundle.

Installing the PEoPL plugin bundle

After opening the standalone, you’ll be greeted by a welcome screen.

Screen Shot 2016-07-27 at 17.48.49

Please navigate to the MPS preferences (may differ on Windows and Linux machines).

Screen Shot 2016-07-28 at 11.45.49

Next, navigate to Plugins and click Install plugin from disk…

Screen_Shot_2016-07-28_at_11_47_34

Select and install the three plugins provided with the bundle in the following order: peoplMbeddrPluginsBundle.zip, peoplCore.zip, peoplBaseLanguageExtension.zip

Screen Shot 2016-07-28 at 11.52.19

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.

newProject

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.

peoplSolution

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.

firstSolution

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 JetBrainsA class container can hold 1…n alternative Java classes, each of which can be used like a normal class.

classContainer

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.

importJava

In this example, we imported the Graph Product Line (GPL) that comes with CIDE. Prior to the import, all Java sources were assigned to a package named GPL.

As you can see, the model indicates that there are some errors, which need a workaround.

importedGPL

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.

errorsVertex

Luckily, the type checker, that comes with MPS, can resolve most of these errors (right-click on the Solution and choose Check Solution).

checkSolution

Next, a tool window pops up. You can press Perform Quick Fixes.

qfixYou can repeat the checking and quick-fixing process a few times until there are no errors left, or the number of errors stays constant. There may be some issues you have to fix yourself.

For instance, unfortunately, the type checker might introduce unnecessary type casts with broken references.
fixyourself

After you have fixed the errors, it’s time to convert the imported classes into the PEoPL format.

convert

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.

afterConvert

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.

pushhints

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)

standardHint

Below, we show the standard annotative editor.

afterhint

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().

intention

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.

assign

It is likely that you need more modules than just Base. We can define new modules in the ModuleDefinitions node in the peoplConfig model.

modDef

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“.
modConf

Please let us know, if you have any questions related to PEoPL or this tutorial.