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. 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. For products with the Embedded UML Target Debugger the same applies for CreateAnimationLibrary.
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. This is very helpful if for a specific µVision project some RXF files should not be deployed.

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

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 µVision, 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.

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. This is very helpful if for a specific µVision project some RXF files should not be deployed.

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.

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.