Papyrus-RT/User/User Guide/Building the RTS

Modifying and Building the Papyrus for Real Time RTS

Introduction

Papyrus for Real Time is a complete modeling environment that provides you with complete code generation from restricted forms of UML, such as UML-RT. This tutorial addresses the particular case of the UML-RT domain-specific modeling language available with Papyrus for Real Time.

In order for the tool to be able to create executable applications, the Papyrus for Real Time not only needs the code generated from the model, but also a set of run-time services that implement the underlying "virtual machine" for the model. This run-time service (RTS) library provides the glue that connect sand enables the various constructs defined by UML-RT, such as messaging, time-related capabilities, dynamic structure control, and support for state machine driven behavior.

Out of the box, Papyrus for Real Time provides a pre-compiled version of this RTS library. However, we do recognize that our choice of toolchain (compiler, etc.) may not be the one you need for your particular project.

This tutorial will show you how you can add your toolchain of choice to the Papyrus for Real Time build process.

 Warning: The rest of this tutorial contains technical information requiring knowledge of operating systems and C++ build environments. If you are not comfortable with the instructions, please find someone to help you! 

Papyrus and Toolchain Versions

 Note: This tutorial was created for Papyrus for Real Time v0.7.0. As such, there may be changes in the steps for later releases. 

In order to be able to compile and link the generated code, the build environment must be set up. The first requirement is regarding the compiler version supported out of the box by the RTS. Within Papyrus for Real Time v0.7.0, the RTS library was pre-built using g++ 4.7.2 (even though the configuration says 4.6.3...), so it is recommended to have that version installed as the default.

If you have g++ 4.7.2 installed or are planning to install it, you should not need to proceed with this tutorial.

If you do not have g++ 4.7.2 installed and do not wish to install it, you can follow the instructions in this tutorial to update the RTS library.

Build Environment

The build environment for the Papyrus for Real Time RTS uses environment variables to define how to proceed and where to find various required files, such as source and make files.

{UMLRTS_ROOT}

Environment variable used by the generated makefile, pointing to the root of the RTS folder. By default, it will point to the RTS folders that are distributed as a plugin ("eclipse/plugins/org.eclipse.papyrusrt.rts_V.R.M.YYYYMMDDHHmm").

This is useful if you do not have write-access to the RTS plugin folder or if you prefer to modify the RTS installation in another location (e.g., under source control). In the case of the latter, you can copy the RTS folder from the plugin to another location and use this environment variable to point at the new Papyrus for Real Time RTS folder.

 Note: Papyrus for Real Time plugin version are identified a suffix of the form "*V.R.M.YYYYMMDDHHmm"*, where:
       V    : single digit version
       R    : single digit release
       M    : single digit modification
       YYYY : four-digit year the plugin was built
       MM   : two-digit month the plugin was built
       DD   : two-digit day of the month the plugin was built
       HH   : two-digit hour of the day the plugin was built, in 24 hour format
       mm   : two-digit minutes the plugin was built 

{TARGETOS}

Environment variable used by the generated makefiles, indicating the targeted OS. Because one of the goals of Papyrus for Real Time is the development of embedded systems, it is possible to define the target OS as something other than the development OS and use cross-compilers. When developing UML-RT models, you would typically set this environment variable to be the same as your development OS so you can easily test the system under development.

You can find the OS that are supported by Papyrus for Real Time in the "{UMLRTS_ROOT}/build/os" folder. For v0.7.0, these are "linux" and "windows". *Note: only a Linux target OS is supported for the Papyrus for Real Time 0.7.0 release. The Windows target OS is available for 'experimentation' only and is 'not* officially supported in the v 0.7.0 release.'

{BUILDTOOLS}

Environment variable used by the generated makefiles that describes the build tools to be used. You can find the ones that are supported by Papyrus for Real Time in the "{UMLRTS_ROOT}/build/buildtools" folder. For v0.7.0, these are "x86-gcc-4.6.3", "x86-gcc-4.6.3-debug", and "x86-VisualC++-12.0". *Note: only the gcc build chain is supported for the Papyrus for Real Time 0.7.0 release. The VisualC++ toolchain is available for 'experimentation' only and is 'not* officially supported in the v 0.7.0 release.'

Target Operating System

If your operating system (OS) is not one of those supported, you will need to create a new OS configuration. This requires adding content in two locations.

{UMLRTS_ROOT}/build/os

This folder contains one folder for each available operating system. If your operating system is not listed, you will need to add a new folder for it and then copy the makefile that is closer to your operating system into that folder before modifying it for your OS-specific build environment setup.

{UMLRTS_ROOT}/os

This folder contains one folder for each available operating systems, but a "stub" folder. You can copy the folder of the operating system that most closely matches yours and modify the files it contains for your needs.

The following files need to be implemented for the RTS to work:

 osbasicthread.cc : implement OS-specific threading mechanism
 osmutex.cc       : implement OS-specific mutual exclusion mechanism
 osnotify.cc      : implement OS-specific notification mechanism
 ossemaphore.cc   : implement OS-specific semaphore mechanism
 ostime.cc        : implement OS-specific mechanism to get current time
 ostimespec.cc    : implement OS-specific mechanism for UML-RT time structure  

 Note: modifying these files require OS-specific C++ programming knowledge. 

And don't forget to also update their respective headers, found in {UMLRTS_ROOT}/{osName}/include, if required.

Toolchain

If your compiler toolchain is not one of those supported, you will need to add its definition.

All the information regarding available toolchains can be found in one folder.

{UMLRTS_ROOT}/build/buildtools

This folder contains one folder for each available toolchain. Note that debug and non-debug versions are separate folders. You can also have separate folders for specific versions of the toolchain. Each toolchain folder contains a single file named "buildtools.mk" that contains the tool specifications

To support a new toolchain, copy one of the existing configurations that most closely ressemble your toolchain and adapt it to your compiler by modifying the "buildtools.mk" file.

Build the RTS

Once this is done, you can recompile the RTS for your environment by going to the {UMLRTS_ROOT} and running the following commands:

# make clean
# make

You now have a new version of the Papyrus for Real Time RTS library with which to build your model executables.

Appendix: Tree of folders and files of interest

This is a pruned tree of the folders and files of interest under {UMLRTS_ROOT}.

os
 +- stub
   +- basedebug.cc
 +- windows
   +- ossemaphore.cc
   +- include
     +- ostime.hh
     +- osutil.hh
     +- osselect.hh
     +- osnotify.hh
   +- osbasicthread.cc
   +- osnotify.cc
   +- ostime.cc
   +- osmutex.cc
   +- ostimespec.cc
 +- linux
   +- ossemaphore.cc
   +- include
     +- ostime.hh
     +- osutil.hh
     +- osselect.hh
     +- osnotify.hh
   +- osbasicthread.cc
   +- osnotify.cc
   +- ostime.cc
   +- osmutex.cc
   +- ostimespec.cc
lib
 +- linux.x86-gcc-4.8.4
   +- librts.a
Makefile
build
 +- host
   +- host.mk
 +- os
   +- default.mk
   +- windows
     +- os.mk
   +- linux
     +- os.mk
 +- buildtools
   +- x86-VisualC++-12.0
     +- buildtools.mk
   +- x86-gcc-4.6.3
     +- buildtools.mk