Papyrus-RT/User Guide/Compiling and running Papyrus for Real Time applications

This page describes how to compile and run applications from code generated with Papyrus-RT.

Preliminaries

This assumes that you have installed Papyrus-RT, and if you are not on Linux, you have followed the steps described in Vagrant Setup or the steps described in Cygwin Setup. In particular we assume that either your host OS is Linux or you have now a Linux VM or you are on Windows and have access to the Cygwin terminal.

• If you are not on Linux and you setup the environment with Vagrant, start up your vagrant Linux VM: go to the command-line and type the following (adapting the path to the location where you installed your Vagrant VM accordingly)

cd /Users/yourusername/vms/my_vm
vagrant up
vagrant ssh

At this point you should be running Linux.

If you have not already done so, install g++ and make. On Ubuntu, you can do these as follows:

sudo apt-get -y install g++ make

• If you are on Windows and you installed Cygwin, run the Cygwin terminal.

Setting up the UMLRTS_ROOT environment variable

To build applications from code generated with Papyrus-RT, the build must link the compiled code to the runtime system (RTS). During a build we must specify where the RTS is located so that it can be linked. We specify this location in a special environment variable called UMLRTS_ROOT.

1. Determine the location of the runtime system.

• If your host OS is Windows or macOS and you followed the instructions from Vagrant Setup, then the RTS will be located at /home/vagrant/rts.

• On all platforms, you can find it as follows:

- If you installed Papyrus-RT with the RCP, then the RTS is located in the plugins folder under the extracted Papyrus-RT. There should be a folder called

org.eclipse.papyrusrt.rts_<version>.<year><month><day><build>

and under this, there should be a subdirectory called umlrts. This is the folder that we are looking for. For example, the full path could be something like this:

/Users/yourusername/tools/PapyrusRT/plugins/org.eclipse.papyrusrt.rts_0.8.0.201701030512/umlrts

- If you installed Papyrus-RT using the Installer and selected the "bundle pool" option, then the plugin is found under ~/.p2/pool/plugins where ~ is your user's home directory. If you didn't select the "bundle pool" option, then it will be located within the plugins folder of the installation folder you selected, as described in the previous option.

2. Once you determined the location of the RTS, add the following line to your .bash_login file (located in your user home directory) or to your .bash_profile file (if it already exists; also located in your user home directory):

export UMLRTS_ROOT=<path-to-the-rts>

For example, if you are on Windows or macOS, and followed the Vagrant Setup instructions, then you can type the following in the console:

export UMLRTS_ROOT=/home/vagrant/rts >> .bash_login

or

export UMLRTS_ROOT=/home/vagrant/rts >> .bash_profile

(The >> .bash_login or >> .bash_profile part will add the line without having to open an editor.)

3. Execute the contents of .bash_login or .bash_profile

source ~/.bash_login

or

source ~/.bash_profile

If you added the setting of the UMLRTS_ROOT environment variable to your .bash_login or .bash_profile, you will not need to export it every time that you login to your VM.

To make sure that you setup the UMLRTS_ROOT environment variable correctly, you can type the following in the console:

env | grep UMLRTS_ROOT

or

echo $UMLRTS_ROOT

and this should show the path to the RTS, if you set it up correctly.

Building the runtime system

Cygwin users
If you are on Windows using the Cygwin setup, skip this section and go directly to Building your applications on Windows with Cygwin

Before you can link the RTS to your code, the RTS itself must be built once. Assuming that you have set the UMLRTS_ROOT environment variable as described in the previous session, do the following:

1. Go the the RTS folder:

cd $UMLRTS_ROOT

2. Do a cleanup:

make clean

3. Build:

make

Normally you need to do this only once. You may have to redo these steps if you update Papyrus-RT, but otherwise you won't need to repeat these.

Building your applications on Linux or Windows or macOS with Vagrant

Assuming that you have set the UMLRTS_ROOT environment variable and built the RTS as described in the previous sections, you can now build code generated with Papyrus-RT.

Suppose that in your modelling environment you created a Papyrus-RT project called MyProject and that you successfully generated code from it. Then, the generated code will be in a project called MyProject_CDTProject in the same workspace. So now you can do the following:

1. If you are on Linux, go to step 2. If you are on Windows or macOS start your vagrant Linux VM if you have not already done so:

cd /Users/yourusername/vms/my_mv
vagrant up
vagrant ssh

2. Navigate to the location of your workspace (if you are on Windows or macOS, you should have specified in the Vagrantfile the location of the workspace as a shared folder). For example

cd ws

3. Go into the generated CDT project's src folder:

cd MyProject_CDTProject/src

4. Build

make

If there are no compilation errors, this will create an executable file, which by default is called TopMain and which you can run by typing

./TopMain

If there are errors, first make sure that the UMLRTS_ROOT environment variable is correctly set as described above. Also make sure that you have built the RTS as described above. If you still get errors, note the error messages issued by g++, and in particular note the lines in the generated code and the errors. These will usually be errors in action code. After making necessary changes, you can try recompiling by running make again. Occasionally, some errors require that you run make clean before running make again.

Building your applications on Windows with Cygwin

Assuming that you have set the UMLRTS_ROOT environment variable and built the RTS as described in the previous sections, you can now build code generated with Papyrus-RT.

1. Open a Cygwin terminal

2. Go to the directory that contains the generated code:

cd <path_to_workspace>/<project_name>_CDTProject 

where <path_to_workspace> is the full path (in Linux-style) to the workspace that you used in Papyrus-RT and <project_name> is the name of your project in Papyrus-RT.

3. Create a build directory inside it and move into it.

mkdir build
cd build

4. Invoke CMake pointing to the src folder:

cmake ../src

This will create a Makefile.

Using Cygwin paths
You might have to change the path prefix in the generated file src/CMakeLists.txt to use Cygwin paths (e.g., /cygdrive/c/...)

5. Invoke Make:

make

This will build the RTS in this build folder (if it has not already been built) and then build the project itself. It will create an executable, called, by default, TopMain.exe.

In theory you will need to invoke cmake only once per project, but run make with each update to the generated code.

Cygwin and MingW co-installation
We have received reports of potential conflicts between MinGW and Cygwin compilers when installed separately in the same environment. As we use Cygwin for our testing, we recommend that users install only Cygwin and ensure that the Path environment variable correctly to point to the Cygwin 'bin' directory.