IDE Integration

Deployment

In Rhapsody you will generate sources, but the build process for your application must be carried out in µVision. This allows you to configure all target dependent settings in µVision which has knowledge on Device and Target. You can even use wizards to configure peripherals, memory maps etc., as these are available in µVision. 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 µVision.

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.
  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. This happens if you uncheck the option RXF Library is used on the Deployment Configuration Dialog.
- NOTE: Which files are actually part of the RXF library can be configured project wide or project specific using exception lists, which can also behave independant of the RXF library checkbox. For details please see the WSTDeployer Exception List help page.
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.

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 <your product> 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 µVision <your product>, 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 µVision project 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 µVision 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

NOTE: When using the option Customize Subfolders, a µVision project file is not updated. This option is merely implemented with flexibility in mind; please refer to the description on how to use GenerateDirectoryPerModelComponent / C_CG:Package:GenerateDirectory in your model and subfolders in µVision.

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 details please see the WSTDeployer Exception List help page.

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 which are in the active component's scope 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

For details please see the WSTDeployer Exception List help page.

Removing files from the IDE project or destination folder after it is not in the component's scope anymore

Most versions of the WSTDeployer do not support removing file references automatically from an IDE project after they have not been regenerated because they are not part of the active component's scope anymore or have been renamed in the model. But the WSTDeployer will notice those redundant source files by analyzing the component's scope and is able to delete those files from the WSTDeployer destination directory. This works independantly of the the Rhapsody feature "Code | Clean Redundant Source Files".
The Deployer for µVision supports the Rhapsody feature "Code | Clean Redundant Source Files". Rhapsody will remove redundant source files which have been deleted or renamed in the model or which are not inside the active component's scope anymore. When these files are deleted from file system by Rhapsody and have already been deployed to µVision earlier, those files will automatically be removed from your µVision project and deploy destination folder. You can also deactivate this feature in the WSTDeployer.properties file by changing PrjRemoveRedundantSourceFiles to false.

You can set the Deployer to deploy files to the same directory as Rhapsody generates them. That way the deployer will not perform the copy operations but keep the files in the uVision project up to date. You need to use this way of working with the Deployer to be able to use Rhapsody's roundtripping machanisms.

The Rhapsody run command and the WSTDeployer may use files called CurrentFileList.txt and PreviousFileList.txt inside the configuration directory. Those files are reserved to be used by WSTDeployer versions which support removal of redundant source file links from IDE projects.

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.

Backups of µVision project files

The Deployer will use an XML parser and modify the .uvproj IDE project file. We tried to add good diagnostics to prevent getting a corrupted project file. In addition to this the WSTDeployer by default creates up to three Backups of the project file. The backups will only be created if the last backup is more than one hour old. Backups will be named including the date and time e.g. GettingStarted.uvproj.Backup_2010-03-26_12-30-05. You can also deactivate this feature in the WSTDeployer.properties file by changing PrjAutoBackup to false.

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.