View source for 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 [[Papyrus-RT/User_Guide/Vagrant_Setup | Vagrant Setup]] or the steps described in [[Papyrus-RT/User_Guide/Cygwin_Setup | 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)

<pre>
cd /Users/yourusername/vms/my_vm
vagrant up
vagrant ssh
</pre>

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:

<pre>
sudo apt-get -y install g++ make
</pre>

* 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 <code>UMLRTS_ROOT</code>.

1. Determine the location of the runtime system.

:* If your host OS is Windows or macOS and you followed the instructions from [[Papyrus-RT/User_Guide/Vagrant_Setup | Vagrant Setup]], then the RTS will be located at <code>/home/vagrant/rts</code>.

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

::- If you installed Papyrus-RT with the RCP, then the RTS is located in the <code>plugins</code> folder under the extracted Papyrus-RT. There should be a folder called
<pre>
org.eclipse.papyrusrt.rts_<version>.<year><month><day><build>
</pre>
::and under this, there should be a subdirectory called <code>umlrts</code>. This is the folder that we are looking for. For example, the full path could be something like this:
<pre>
/Users/yourusername/tools/PapyrusRT/plugins/org.eclipse.papyrusrt.rts_0.8.0.201701030512/umlrts
</pre>
::- If you installed Papyrus-RT using the Installer and selected the "bundle pool" option, then the plugin is found under <code>~/.p2/pool/plugins</code> where <code>~</code> is your user's home directory. If you didn't select the "bundle pool" option, then it will be located within the <code>plugins</code> 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 <code>.bash_login</code> file (located in your user home directory) or to your <code>.bash_profile</code> file (if it already exists; also located in your user home directory):
<pre>
export UMLRTS_ROOT=<path-to-the-rts>
</pre>
:For example, if you are on Windows or macOS, and followed the [[Papyrus-RT/User_Guide/Vagrant_Setup | Vagrant Setup]] instructions, then you can type the following in the console:
<pre>
export UMLRTS_ROOT=/home/vagrant/rts >> .bash_login
</pre>
:or
<pre>
export UMLRTS_ROOT=/home/vagrant/rts >> .bash_profile
</pre>
:(The <code>>> .bash_login</code> or <code>>> .bash_profile</code> part will add the line without having to open an editor.)

3. Execute the contents of <code>.bash_login</code> or <code>.bash_profile</code> 
<pre>
source ~/.bash_login
</pre>
:or
<pre>
source ~/.bash_profile
</pre>

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

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

<pre>
env | grep UMLRTS_ROOT
</pre>

or

<pre>
echo $UMLRTS_ROOT
</pre>

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


== Building the runtime system ==

{{ Note | 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|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 <code>UMLRTS_ROOT</code> environment variable as described in the previous session, do the following:

1. Go the the RTS folder:
<pre>
cd $UMLRTS_ROOT
</pre>

2. Do a cleanup:
<pre>
make clean
</pre>

3. Build:
<pre>
make
</pre>

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 <code>MyProject</code> and that you successfully generated code from it. Then, the generated code will be in a project called <code>MyProject_CDTProject</code> 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:
<pre>
cd /Users/yourusername/vms/my_mv
vagrant up
vagrant ssh
</pre>

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
<pre>
cd ws
</pre>

3. Go into the generated CDT project's src folder:
<pre>
cd MyProject_CDTProject/src
</pre>

4. Build
<pre>
make
</pre>

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

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 <code>make</code> again. Occasionally, some errors require that you run <code>make clean</code> before running <code>make</code> 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: 
<pre>
cd <path_to_workspace>/<project_name>_CDTProject 
</pre>
:where <code><path_to_workspace></code> is the full path (in Linux-style) to the workspace that you used in Papyrus-RT and <code><project_name></code> is the name of your project in Papyrus-RT.

3. Create a build directory inside it and move into it. 
<pre>
mkdir build
cd build
</pre>

4. Invoke CMake pointing to the src folder: 
<pre>
cmake ../src
</pre>
:This will create a <code>Makefile</code>. 

{{warning | 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: 
<pre>
make
</pre>
: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, <code>TopMain.exe</code>.

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

{{warning | 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.}}