IDE integration

Deployment

In Rhapsody you will generate sources, but the build process for your application must be carried out in your IDE. This allows you to configure all target dependent settings in the IDE you are familiar with. You can even use wizards to configure peripherals, memory maps etc., when these are available in the IDE. Therefore, the generated sources must be copied into your environment, together with some RXF and configuration files so afterwards you will be able to build your application.

The Deployment tool is a separate tool which will copy the necessary sources and generated configuration to your IDE, and add these to a workspace or project file, so they become visible in your IDE.

The Deployment tool will use tags of a stereotype in your Rhapsody model, which come with profile(s) which are part of your product.These tags will store information like the name of your workspace and workspace or project file, but not any paths. The path information is stored by Deployer on your PC instead, so your Rhapsody model can be deployed to different locations or PC's, without changing your model.

The deployer will ask you some paths the first time you launch it for a particular project (UML model) and environment (RXF version): the next time it knows where to deploy to, so does not ask you. (Via a Rhapsody tools menu however, you are able to modify existing settings).
In order to be able to build your application in your environment, the Deployment tool needs to copy:

the Rhapsody generated sources.
the RXF source files.

Usually the IDE project is using the Framework in a library format and only headers and dimensioning RXF files are deployed. In this case, the exception list Tools\WSTDeployer\WSTDeployerExcludedFilesLib.txt is used.
The Framework libraries need to be build with exactly the same options, memory model etc. used in the application. Recompiling the libraries is possible via CreateRXFLibrary IDE project, which can be found in Samples\Code\CreateRXFLibrary.
It is also possible to deploy all RXF source files and directly compile them in your IDE together with your application. If you uncheck the option RXF Library is used on the Deployment Configuration Dialog, the file Tools\WSTDeployer\WSTDeployerExcludedFilesNoLib.txt is used.
NOTE: It is also possible to use a project specific file WSTDeployerExcludedFiles.txt in the IDE project's directory, which is independant of the RXF library checkbox.

configuration files. These typically include RXF options as #defines and other details for your environment needed when building your application. The RXF has some data structures which can be configured regarding their size: for this the file RxfDimensions.h is generated when you press Build in Rhapsody. Also RxfConstants.h and WSTMemoryTypes.h will usually be generated when pressing build in Rhapsody.

The machine dependent destination paths needed to copy all files, are stored in the Windows registry of your PC. The default values for relative subfolders of the specified destination root path can be overridden. They are taken from the UML model where these are kept in the form of tags which belong to a specific stereotype for components. However, the default paths used rely on relative paths towards a root: usually one needs to specify this root only.

The deployment tool operates in two modes:

a configuration mode. If you press Run in Rhapsody, the WSTDeployer is launched. When it detects that for the model or Rhapsody project and environment no data is stored yet in the Windows registry, it will pop up a configuration dialog. The only way to reconfigure an existing project for an environment again, is to launch the WSTDeployer via the Rhapsody Tools menu - which you must adapt once. WSTDeployer will save all data in the Windows registry via the key HKEY_CURRENT_USER\Software\JavaSoft\Prefs\de\willert\deployer.
a copy mode. After a Code | Generate and a Code | Build in Rhapsody, you must activate the WSTDeployer via the Tools menu. When it is launched and finds data that for the model or Rhapsody project and environment in the Windows registry, it will use that data.

WSTDeployer is written in Java. Its launch may take a few seconds due to loading the Java VM.
You may not see any progress but please have patience.

The Deployer does not support the Rhapsody feature Code | Clean Redundant Source Files. Rhapsody will remove redundant source files, but when these are already deployed to your IDE, those files are not removed from your IDE project.
You can use a workaround for now, by instructing Rhapsody not to use the Default path to generate files which also enables roundtripping

In the next paragraphs, you will learn how to get your files deployed in your environment so your application can be build there.

Configuring the Rhapsody Model

To allow the WSTDeployer to copy the Rhapsody generated files into model and user specific paths, the stereotype RXFComponent from the profile has to be assigned to the active component.

By adding the RXFComponent stereotype, tags were added to the component, which need to be set up first. The screenshots show example values which could match the settings needed to deploy the software to a specific IDE environment. You can also set the tag values up for any other IDE project.

Tags set up in the component

For most environments and IDEs, the following tags have to be set up correctly:

rootDescription: A short text to inform developers working on the model, to what kind of build environment the model should be deployed. It can also include a non machine dependent hint, where the IDE project's root directory is found. It is displayed in the WSTDeployer GUI.
rootTitle: A short title for the IDE project's machine specific root path. It is displayed in the WSTDeployer GUI.
relativeGeneratedFilePath: Specifies, where files Rhapsody generates from the UML model for the active component should be deployed to.
relativeRxfPath: Specifies, where the Realtime eXecution Framework files should be deployed to.
toolchainProjectFile: Specifies the filename of the IDE's project or workspace file, if the IDE integration supports to modify the project.

With custom versions of Deployment.java, Constants.java, ToolchainGateway.java or WSTDeployer.properties it is possible to use a different set of tags for deployment. For details see IDE integration and Interfaces.

All path tags with the "relative" prefix are always relative to an IDE project's root directory.

Configuring User Specific Paths

The tags in the Rhapsody model only use relative paths to keep the model independent on user or machine specific paths. Before the files can be deployed, at least the correct root path of the build environment has to be specified in the WSTDeployers configuration GUI.

Note: The WSTDeployer can only be started (in configuration or deployment mode) if Rhapsody is running and the Rhapsody project with the stereotypes and tags set up is loaded.

When WSTDeployer runs and does not detect data in the Windows registry on your project / environment combination, it will enter the configuration mode. If you want to have WSTDeployer to show configuration data on a known project / environment combination, you must launch it via the Rhapsody Tools menu - but you must configure this menu first. In order to be able to configure the Tools menu, we must first create or open a project. Adding the WSTDeployer configuration mode to the tools menu is described on the WSTDeployer installation page.

When WSTDeployer starts in configuration mode, the configuration dialog will initially not contain any absolute paths. It should only have read the tags with the relative paths and the root path and description texts from Rhapsody:

Nothing configured yet

Enter the path for your build environments root directory. You can also use the "..." button to browse for a directory. All other text fields will just be readable to verify the resulting paths with the relative paths appended.
This is the most probable use case.

Using default relative paths

Customize Subfolders

If the relative paths for some reason do not match with the directory structure you use and the relative paths are correct for most developers working on the project, you can select to customize the subfolders. Then the root directory was only used to initially fill in paths for the subfolders. However, the root path is still editable because in most environments the root specifies, where the project or workspace file can be found. You can edit them freely now:

Customized Paths

When using the option Customize Subfolders, an IDE project file is not updated.

RXF Library

You have the option not to use the RXF in a library form, but use the RXF in source form, which you can influence with the checkbox RXF Library used.

For maximum flexibility, you can use this checkbox plus an exception list to define which files must be deployed or not:

if the checkbox RXF Library is used is checked, the exception list WSTDeployerExcludedFilesLib.txt in the directory<your Rhapsody>\Share\WST_RXF_V5\<your product>\Tools\WSTDeployer is used.
This list contains the names of the files which are normally part of the RXFD or RXFR library you can create with CreateRXFLibrary project.
As a result, only the files which contain dimensioning details such as arrays which contain constants set via properties or compile flags, are deployed except those files specified in WSTDeployerExcludedFilesLib.txt
if the checkbox RXF Library is used is unchecked, the exception list WSTDeployerExcludedFilesNoLib.txt is used.
As a result, all RXF files are deployed except those files specified in WSTDeployerExcludedFilesNoLib.txt
NOTE: It is also possible to use a project specific file WSTDeployerExcludedFiles.txt in the IDE project's directory, which is independant of the RXF library checkbox..

Saving Deployer Settings

The Deployer stores the configuration in your Windows registry. The paths are stored depending on the following factors:

Logged in user (uses the registry path HKEY_CURRENT_USER)
Currently opened Rhapsody project name
Active Component Name
Title of the build environment root path
The selected release/environment

This makes sure configurations for different projects or even multiple components for different product versions within one project do not get mixed up and will all be saved separately.

Deploying Files

After the generation of your files (component files generated from your model and configuration files), you must press Build

to generate the RXF configuration files. Next, press Run Run Button

to launch WSTDeployer. It will copy the files automatically if it does not enter the configuration mode on a new project / environment combination:

Progress bar window

Deployment Log File

In the WSTDeployer directory a log file WSTDeployerLog.txt will be created and each run of the deployer appends information, warnings and errors about the deployment. If the WSTDeployer is started with the debug command as first argument, also debugging information is written to the log file.

The log file WSTDeployerLog.txt is limited to a size of 512kB. If the size is exceeded, the file will be renamed to a backup log file named WSTDeployerLog.txt.1 and a new WSTDeployerLog.txt will be started. If an older WSTDeployerLog.txt.1 already existed, it will be truncated. This makes sure the log files never consume more than 1MB of hard disk space.

Setting up a Project Specific WSTDeployerExcludedFiles.txt

The WSTDeployer can also use individual settings, which files to deploy, for a specific IDE project. This is helpful, if an environment bridge, e.g. WSTTarget.c should not be copied from the product's Sources directory, but will be generated from Rhapsody or is included manually in the IDE project. For details about customized bridge files please see <your Rhapsody>\Share\WST_RXF_V5\<your product>\Doc\Books\RXFDeployerGuide.pdf.

To override the general exception lists WSTDeployerExcludedFilesLib.txt and WSTDeployerExcludedFilesNoLib.txt in the directory <your Rhapsody>\Share\WST_RXF_V5\<your product>\Tools\WSTDeployer, you need to place a file WSTDeployerExcludedFiles.txt in your IDE project directory. This is the directory you also specify in the WSTDeployer configuration dialog as deployment root.

NOTE: The individual deployment exception list must not contain the postfix Lib or NoLib in the filename, it is just named WSTDeployerExcludedFiles.txt.

Working with a Relative Root Path

It is possible to specify the root path of your destination IDE project not just as an absolute path (which is usually done via the "..." browse button), but manually enter a relative path. It is not possible to enter any relative path just like "..\IDE_Project" or "IDE_Project". Instead if a relative path should be used it must begin with a single point-backslash: ".\", so the two examples would need to be entered as ".\..\IDE_Project" and ".\IDE_Project". The path will always be relative to the <Active Component>\<Active Configuration> directory where Rhapsody generates the code.

WSTDeployer Command Line Options

When using the WSTDeployer in a batch execution environment, e.g. to perform regression tests, it can be useful to directly call the deployer with some of the command line options:

configure Displays a configuration dialog to see and change the configured paths.
deploy Copies files from the Rhapsody model to the configured paths.
version Displays the tool's version string.
debug Generates a more detailed log file, should be first argument.
setRoot(path) Sets the root path to the specified argument within the brackets and switches custom paths off without displaying a dialog. If the path contains spaces it has to be quoted, e.g. setRoot("C:\Program Files\Dest").
quitRpy Quits Rhapsody after having executed commands which came first. This can be useful for batch processing and regression tests.
quitRpySave Quits Rhapsody and saves all changes after having executed commands which came first. This can be useful for batch processing and regression tests.

The WSTDeployer interpretates command line arguments one after the other. This means the order of command line options defines which commands will be executed first.