Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Papyrus-RT/User Guide/Vagrant Setup

< Papyrus-RT‎ | User Guide
Revision as of 12:22, 16 January 2017 by Eposse.gmail.com (Talk | contribs) (Fixed typos)

Papyrus-RT consists of two major components: a modelling environment, and a runtime environment. The modelling environment provides a GUI where you can create and edit models, as well as generate code from them. This is an Eclipse-based application. The runtime environment is a runtime system (RTS) together with a runtime services library that are used to run generated code.

Because the Papyrus-RT modelling environment is based on Eclipse, it runs on all major platforms. This means that you can use it in your preferred operating system to do modelling.

However, in the current version of Papyrus-RT (0.8), the runtime system runs on Linux. This means that if you do modelling on Windows or macOS, you will need to do some additional setup to be able to execute code generated in the modelling environment. These instructions describe how to achieve this for users on non-Linux platforms. Linux users can skip these and go directly to Compiling and running Papyrus for Real Time applications.

Note.png
Paths on Windows vs. paths on Linux and macOS
The rest of these instructions will use the standard convention used by Unix-like operating systems like Linux and macOS for paths, using the slash character / as separator for folders. For example
/Users/yourusername/somefolder/

If you are on Windows, you will need to use the corresponding convention, which starts paths with the drive letter and uses backslash \ as separator. The example above would be written as

C:\Users\yourusername\somefolder\


Prerequisites

You will need a Virtual Machine (VM) running Linux. A Virtual Machine runs some operating system (aka the "guest OS") inside another (aka the "host OS"). In our case, the guest OS will be Linux, and the host OS can be Windows or macOS. You will need to install two components:

We recommend VirtualBox as hypervisor, since this is the one where we have done all testing.

  1. Install VirtualBox:
    1. Go to VirtualBox downloads
    2. Download the package for your OS.
    3. Install it according the the instructions in the VirtualBox User Manual: VirtualBox installation instructions
  2. Install Vagrant:
    1. Go to Vagrant downloads
    2. Download the package for your OS
    3. Install it according the the instructions in the Vagrant documentation: Vagrant installation instructions


Note.png
Set the Path environment variable
On Windows you may have to edit your Path environment variable to point to the folders with the VirtualBox and the vagrant executables. See How to set the path and environment variables in Windows


Creating the VM

1. Open a terminal/console/command-prompt window

2. Go to some folder where you want to store the new VM environment. E.g.

cd /Users/yourusername/vms
Note.png
In the rest of these instructions we will assume this is the path where we are installing the VM. You can choose any suitable folder, and adapt the rest of the instructions accordingly.


3. Create a folder for your VM:

mkdir my_vm
cd my_vm

4. Create the VM:

vagrant init hashicorp/precise32

5. Set it up: the first time you run the commands below it will take a while, as it downloads the VM image.

  • If using VirtualBox:
vagrant up
  • If using VMware-Fusion:
vagrant up --provider=vmware_fusion
  • If using AWS:
vagrant up --provider=aws

At this point, vagrant will download the guest OS and create a VM for your provider, and then the VM will be up and running. In this case, hashicorp/precise32 is a very lightweight Ubuntu 12.04 LTS with no GUI. The Vagrant Cloud lists alternative VMs, but this one is more than enough for building and running code generated with Papyrus-RT.


Starting and running the VM

The following are the basic commands to interact with your VM from your host OS:

Command Where is it executed Result
vagrant up In the host OS Starts (turns on) the VM
vagrant ssh In the host OS Connects to the VM via ssh, i.e. starts an ssh terminal session
vagrant halt In the host OS Stops (turns off) the VM
vagrant suspend In the host OS Saves the state of the VM and makes it go to sleep
vagrant reload In the host OS Reloads the VM if it is already up
vagrant status In the host OS Displays the current status of the VM
vagrant destroy In the host OS Destroys the VM and removes all its contents. Be careful with this!
exit In the guest OS Exists the VM ssh session


So, with these commands, the typical session consists of the following steps:

1. Open a terminal/console window.

2. Go to the VM installation folder

cd /Users/yourusername/vms/my_vm

3. Start the VM

vagrant up

4. Once it is up, you can connect to it via ssh:

vagrant ssh

This will run the terminal for your VM. The default user is called vagrant and has root status.

5. In the ssh terminal, execute any commands that you'd like. In our case, these will be Linux commands.

6. When done, exit and go back to your host OS:

exit

7. Stop the VM

vagrant halt


Setting up shared folders

Your modelling environment and your workspace (where your projects are located) are in the host OS, and the runtime environment is in the guest OS, but the generated code in your workspace is to be compiled in the runtime environment and therefore the runtime environment needs access to the workspace. Furthermore, the runtime system is packaged with your Papyrus-RT installation in your host OS, and this is also needed to compile generated code.

So in order to compile and execute code generated in your modelling environment, we need a way to give the guest OS access to the folder in the host OS where you generate code and the folder where the runtime system is located.

This is done by telling Vagrant that some folders are shared between the host OS and the guest OS.

By default the folder where you created the VM in your host is shared with the VM's /vagrant folder, so the contents of

/Users/yourusername/vms/my_vm

in your host OS will be the same as

/vagrant

in the guest OS.

But since your workspace and runtime are located somewhere else in your host, we need to specify those locations.


1. Determine the location of your workspace in your host OS. For example, this could be /Users/yourusername/tools/PapyrusRT/ws

2. Determine the location of the runtime system (RTS) packaged with Papyrus-RT. The location depends on how you installed Papyrus-RT.

  • 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.

3. On your host OS go to the VM root folder

cd /Users/yourusername/vms/my_vm

4. In a plain text editor open the file "Vagrantfile" and find the line

    # config.vm.synced_folder "../data", "/vagrant_data"

5. Uncomment the line by removing the leading #

6. Replace ../data with the path to some folder in your host OS (for example, the path to your workspace)

7. Replace /vagrant_data with the path to some folder in your guest OS. For example, the line could be

config.vm.synced_folder "/Users/yourusername/shared_with_vm" "/home/vagrant/shared_with_host"

For Papyrus-RT you need to share at least your workspace folder and the folder where the RTS is located. For example, if your workspace on the host OS is /Users/user/Users/yourusername/tools/Papyrus-RT/ws and the RTS is at /Users/user/Users/yourusername/tools/Papyrus-RT/plugins/org.eclipse.papyrusrt.rts_0.8.0.201611151048/umlrts you should have

config.vm.synced_folder "/Users/user/Users/yourusername/tools/Papyrus-RT/ws" "/home/vagrant/ws"
config.vm.synced_folder "/Users/user/Users/yourusername/tools/Papyrus-RT/plugins/org.eclipse.papyrusrt.rts_0.8.0.201611151048/umlrts" "/home/vagrant/rts"

8. Reload the VM:

vagrant reload

The next time that you do vagrant ssh the folders will be shared, so in the VM, the workspace will be at /home/vagrant/ws and the runtime system at /home/vagrant/rts


Provisioning the VM with g++ and make

In order to build your generated code we need to have the GNU C++ compiler and the GNU Make tools:

1. Login to your vagrant box

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

2. Install g++ and make

sudo apt-get -y install g++ make

Now you should be able to compile C++ projects.


There is one last step, which is building the RTS itself from the sources, so that you can link it when building your generated code. This is explained here: Papyrus-RT/User Guide/Compiling and running Papyrus for Real Time applications.

Back to the top