Papyrus-RT/Developer/Developer Guide/DevEnv Mars

Setting up the Mars Development Environment

There are several possible ways to make a development environment to work on PapyrusRT, but it's a good idea to follow the steps provided here as we know these work.

Installing Eclipse

1. Install Java 1.7 (other Java versions may cause trouble) from http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
2. Download the plain Eclipse SDK 4.5 (Mars) from http://download.eclipse.org/eclipse/downloads/, selecting the one specific to your development platform.
3. Decompress the archive in some target folder. For example: ~/dev/papyrusrt
4. Start Eclipse
5. Go to Preferences -> Java -> Installed JRE and select one that is 1.7
6. Go to Preferences -> Java -> Compiler and under "Compiler compliance level" select 1.7

Installing required development features

Adding required update sites

Go to Help -> Install New Software..., and add each of the following update sites (by clicking on the Add... button).

Name	Location
Xtext	http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
Papyrus releases - mars	http://download.eclipse.org/modeling/mdt/papyrus/updates/releases/mars/
PapyrusRT releases - mars	http://download.eclipse.org/papyrus-rt/updates/releases/mars/
PapyrusRT codegen/rts nightly - mars	http://download.eclipse.org/papyrus-rt/builds/nightly/
PapyrusRT tooling/profile nightly - mars	https://hudson.eclipse.org/papyrus-rt/job/Papyrus-RT-Master-All/lastSuccessfulBuild/artifact/repository/

• The Xtext update site is needed in order to obtain the required version 2.9 as the Eclipse Mars update site only has version 2.8.4
• The different PapyrusRT repositories will give you the possibility of installing allow you to install features depending on what part of PapyrusRT you want to work on.
  

Installing the required features

Install each of the following features by clicking on Help -> Install New Software... and selecting the appropriate update site.

• From the Mars releases update-site:
  • EMF Eclipse Modeling Famework SDK 2.11.1 or newer (found under 'Modeling')
  • C/C++ Development Tools 8.8.0 or newer (found under 'Programming Languages')
  • EGit Team Provider 4.0.3 or newer (found under 'Collaboration')

• From the Xtext update-site:
  • Xtext Complete SDK 2.9.1 or newer (found under 'Xtext')
  • Xtext Redistributable 2.9.1 or newer (found under 'Xtext')

• From the Papyrus releases - mars update-site:
  • Papyrus UML 1.1.3 or newer (under 'Papyrus')
  • Papyrus UML Developer Resources 1.1.3 or newer (under 'Papyrus')
  • Papyrus C++ profile, view and and code generation (Incubation) 1.1.3 or newer (under 'Papyrus Extras (Other)')
  • Papyrus C++ profile, view and code generation Developer Resources (Incubation) 1.1.3 or newer (under 'Papyrus Extras (Other)')

• From the PapyrusRT releases - mars update-site:
  • Papyrus RT Core Feature (Incubation) 0.7.2 or newer
  • Papyrus RT Core Feature (Incubation) Developer Resources 0.7.2 or newer
  • Papyrus RT Feature (Incubation) 0.7.2 or newer
  • Papyrus RT Feature (Incubation) Developer Resources 0.7.2 or newer
  • Papyrus RT Profile Feature (Incubation) 0.7.2 or newer
  • Papyrus RT Profile Feature (Incubation) Developer Resources 0.7.2 or newer
  • Papyrus RT Tooling Feature (Incubation) 0.7.2 or newer
  • Papyrus RT Tooling Feature (Incubation) Developer Resources 0.7.2 or newer

You can install the tooling features from the PapyrusRT tooling/profile nightly update site if you prefer.

Optional features (recommended)

The following features, found in the "Mars" releases update-site, are not required, strictly speaking, but they are very useful to do development on PapyrusRT.

• From the "Mars" releases update-site at http://download.eclipse.org/releases/mars/
  • Ecore Diagram Editor SDK 3.0.1 or newer (found under 'Modeling'; aka EcoreTools; includes Sirius)
  • Mylyn Task List 3.17.0 or newer (under 'Collaboration')
  • Mylyn Task-Focused Interface 3.17.0 or newer (under 'Collaboration')
  • Mylyn Tasks Connector: Bugzilla 3.17.0 or newer (under 'Collaboration')
  • Mylyn Tasks Connector: Gerrit 3.17.0 or newer (under 'Collaboration')
  • Eclipse XML Editors and Tools 3.7.1 or newer (found under 'Programming Languages' and 'Web, XML, Java EE and OSGi Enterprise Development')
  • m2e - Maven Integration for Eclipse 1.6.2 or newer (under 'General Purpose Tools')

• From the FindBugs update-site at http://findbugs.cs.umd.edu/eclipse:
  • FindBugs 3.0.1 or newer

Clone the repositories

You need to clone the PapyrusRT repository (https://git.eclipse.org/r/papyrus-rt/org.eclipse.papyrus-rt.git), and optionally the Papyrus repository (http://git.eclipse.org/gitroot/papyrus/org.eclipse.papyrus.git) if you want to work on the tooling side.

Git repositories are cloned from the "Git Perspective" (Window -> Perspective -> Open Perspective -> Other... and select "Git")

In this perspective, under the "Git Repositories" view (on the left of the work area), click the "Clone" button (it has a bluish curved arrow). Enter the appropriate URI and credentials.

Once you've entered those, you'll be asked for a branch to clone. Select "master". Then you'll be asked to chose a destination folder and whether to import the projects. Usually you want to import the projects, but if you clone the Papyrus repository you might want to say no, as it is very large. It's better for Papyrus to import only some projects as needed to resolve dependencies.

Clone the PapyrusRT repository

The following needs to be provided:

URI	https://git.eclipse.org/r/papyrus-rt/org.eclipse.papyrus-rt.git
Host	git.eclipse.org
Repository path	/r/papyrus/org.eclipse.papyrus.git
Protocol	https
Port	(leave blank)
User/password	You can clone this repository using "anonymous" for your credentials, or use your own Eclipse credentials if you plan to contribute to PapyrusRT itself.

1. Click the Next button.
2. Select the appropriate branch. For most users it should be only the "master" branch. You can clone all branches if you like.
3. Click the Next button.
4. Select a target directory where the git cloned local repository will be stored.
5. Select "Import All Projects". You may organize them in "Working sets" if desired. This might be useful, for example to have separate working sets for the code generator sources, the tests, etc.
6. Click the Finish button.

• The protocol is https rather than http, and the repository path begins with /r/ rather than /gitroot/.
• Whenever you update either the Papyrus or Papyrus-RT features, you should do a git pull on the relevant git repositories. In the case of Papyrus, a mismatch between the "production" version (the installed feature) and the "development" version (the cloned repository) may result in many runtime errors.
  

Clone the Papyrus repository (optional)

You don't need the Papyrus git repository but it may be useful, specially if you are going to work on the tooling side of PapyrusRT.

URI	http://git.eclipse.org/gitroot/papyrus/org.eclipse.papyrus.git
Host	git.eclipse.org
Repository path	/gitroot/papyrus/org.eclipse.papyrus.git
Protocol	http
Port	(leave blank)
User/password	You can clone this repository using "anonymous" for your credentials, or use your own Eclipse credentials if you plan to contribute to Papyrus itself.

1. Click the Next button.
2. Select the appropriate branch. For most users it should be only the "streams/1.1-maintainance" branch for the Mars release (the master branch is for the Neon release).
3. Click the Next button.
4. Select a target directory where the git cloned local repository will be stored.
5. Click the Finish button.

It is recommended *NOT* to import all Papyrus projects. There is a very large number of projects and importing them all will cause Eclipse to try to build them all, which might take a very long time and even stall. For working with PapyrusRT you only need those projects cloned, not imported.

Configure your git repositories

On each of the repositories you should do a "Gerrit Configuration":

1. Select and unfold the repository
2. Select and unfold "Remotes"
3. Right-click on "origin"
4. Click on "Gerrit Configuration" (a small green icon appears on the repository)
5. Click on "Finish".
6. Select and unfold "Branches"
7. Select and unfold "Local"
8. Right-click "master"
9. Click on "Configure Branch..."
10. Set "Remote" to "origin"
11. Set "Upstream branch" to "refs/heads/master"
12. Set "Rebase" (tick the checkbox)
13. Click "OK"

Configure your preferences

To commit code, every Git commit must have the correct credentials. (E)Git must be configured with your name and e-mail used as an Eclipse committer.

1. Go to Window->Preferences... (or Eclipse->Preferences... on a Mac)
2. Navigate to Team->Git->Configuration
3. Under "User settings" check if there is a "user" field with "name" and "email" sub-fields.
   1. If the fields are present and the values correct, nothing needs to be done.
   2. If the fields are present and the values are incorrect, edit them by clicking on the value.
   3. If the fields are not present, click on "Add Entry..." And enter "user.name" (resp. "user.email") as key, and the appropriate value. Click OK.

To be able to compile Xtend code from the code generator, the Eclipse editors must be set to use UTF-8 encoding.

1. Go to Window->Preferences... (or Eclipse->Preferences... on a Mac)
2. Navigate to General->Workspace
3. Under "Text file encoding" check that it is UTF-8. If not, select UTF-8 from the listbox and click OK.

Also, the Java editors should be configured so that code is not re-formatted with every save action, because otherwise, when pushing a change-set to Gerrit, formatting changes will be passed on as "real" changes.

1. Go to Window->Preferences... (or Eclipse->Preferences... on a Mac)
2. Navigate to Java->Editor->Save Actions
3. Ensure that "Perform the selected actions on save" is unchecked.

Generate code for EMF models

The code generator has several internal EMF (meta)models. The repository stores these meta-models but not the generated Java source code for them, which is needed to compile the code generator. These meta-models are found in the 'model' folder of the following projects:

• org.eclipse.papyrusrt.xtumlrt.common.model
• org.eclipse.papyrusrt.xtumlrt.statemach.model
• org.eclipse.papyrusrt.xtumlrt.statemach.ext.model
• org.eclipse.papyrusrt.xtumlrt.umlrt.model

To generate these source code you need to do the following for each of these projects:

1. Open the project org.eclipse.papyrusrt.xtumlrt.XXXX.model
2. Open the folder model
3. Open the file called XXXX.genmodel (e.g. common.genmodel)
4. A tree editor appears, showing the root element. Right-click on the root element.
5. Select "Generate Model Code"

Generate Xtext artifacts

1. Go to the org.eclipse.papyrusrt.xtumlrt.xtext project
2. Navigate to the src/org.eclipse.papyrusrt.xtumlrt.xtext folder
3. Right-click on the Tumlrt.xtext file
4. Select Generate Xtext Artifacts
5. In the console window it may ask you if you agree to download and install ANTLR (the parser generator). Type 'y' (for yes).

Clean all

Once you finish, do a clean build: Project -> Clean... and select all projects.

Depending on your setup, some projects might show errors, in particular the projects for the runtime and the tooling, but the codegen projects should show no errors.

• If you are working on the code generator or runtime, you may choose to close (or remove from your workspace) all the tooling projects (their name starts with org.eclipse.papyrusrt.umlrt.
• If you are working on the tooling, you may close all the code generator projects (their name starts with org.eclipse.papyrusrt.codegen and org.eclipse.papyrusrt.xtumlrt). However, you may still need to import several projects from the Papyrus repository to resolve compilation errors.
• You may also choose to close or remove the test models (their name does not have a prefix).

Define run/debug configurations (optional)

To quickly launch PapyrusRT either as an Eclipse product or as a stand-alone generator, it is convenient to define debug/run configurations. This can be done by selecting Run->Run Configurations... or Run->Debug Configurations.... Below, we describe the settings for an Eclipse-based run, and for a stand-alone run.

Eclipse-based run/debug configuration

On the left pane select "Eclipse Application" and click the New button.

• On top, enter the name for the new run configuration, e.g. "papyrusrt".
• On the Main tab:
  • Under "Workspace Location" choose a location of your preference.
  • Under "Program to Run" select "Run a product" and choose org.eclipse.sdk.ide
  • Under "Execution Environment" choose Java 1.7
• On the Arguments tab:
  • Under "VM Arguments" add -XX:MaxPermSize=512m -Xms512m -Xmx2048m

Standalone run/debug configuration

On the left pane select "Java Application" and click the New button.

• On top, enter the name for the new run configuration, e.g. "papyrusrt - standalone".
• On the Main tab:
  • Under "Project" select org.eclipse.papyrusrt.codegen.standalone
  • Under "Main class" select org.eclipse.papyrusrt.codegen.standalone.StandaloneUMLRTCodeGenerator
• On the Arguments tab:
  • Under "Program Arguments" enter

-d -l ALL -s -p <path-to-eclipse-plugins-folder> -o <output-folder> <input-model>

where

The <input-model> is the .uml file.

Flags:

• -d : debug mode
• -l ALL : log all messages (debug, info, warning, error)
• -s : print the stack trace in case of an exception
• -p <path-to-eclipse-plugins-folder> : specify the <path-to-eclipse-plugins-folder> which can be a ':' separated list. It's useful to include the plugins/umlrt folder of your local git repository (e.g. .../git/org.eclipse.papyrus-rt/plugins/umlrt)
• -o <output-folder> : The <output-folder> can be any folder. It's a good idea to make it specific for your model.