Rose / ClearCase Integration README ** New Feature - Rose 2002 / ClearCase Integration ** ----------------------------------------------------- When performing ClearCase actions on a unit in a Rose model, the ClearCase Add-In will now perform CM status checking on all ClearCase elements within the model. This provides an opportunity to perform the same ClearCase action on any element which applies. When the ClearCase dialog is displayed, you will have an opportunity to perform the selected ClearCase action on any or all of the ClearCase elements presented in the dialog. The CM status checking which is performed to provide this new capability can at times seem lengthy if working with a large model. In this case, you may elect not to utilize this feature by placing the following in either your $USER.reg (applies to single user) or the rational_dir/releases/rose.2002.05.00/registry/rose.reg file (applies to anyone using the release): [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software\Rose\AddIns\ClearCase\Custom Settings] "ShowAll"="No" Once the registry file is edited the user(s) should run rational_dir/releases/rose.2002.05.00/bin/rose_cleanup and then run 'rose' for the change to take effect. *** The following instructions were created for Rose/ClearCase Integrations when using ClearCase 3.2.1 or before. Many of the same issues apply when using both ClearCase 3.2.1 and ClearCase 4.x, however, there have been enhancements to ClearCase 4.x which provide greater support for Rose elements. **After reviewing the following information, if you are using ClearCase 4.x, see the section entitled: "Integration with Rose and ClearCase 4.x" New Feature - Rose 2002 / ClearCase Integration ----------------------------------------------- When performing ClearCase actions on a unit in a Rose model, the ClearCase Add-In will now perform CM status checking on all ClearCase elements within the model. This provides an opportunity to perform the same ClearCase action on any element which applies. When the ClearCase dialog is displayed, you will have an opportunity to perform the selected ClearCase action on any or all of the ClearCase elements presented in the dialog. The CM status checking which is performed to provide this new capability can at times seem lengthy if working with a large model. In this case, you may elect not to utilize this feature by placing the following in either your $USER.reg (applies to single user) or the rational_dir/releases/rose.2002.05.00/registry/rose.reg file (applies to anyone using the release): [HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software\Rose\AddIns\ClearCase\Custom Settings] "ShowAll"="No" Once the registry file is edited the user(s) should run rational_dir/releases/rose.2002.05.00/bin/rose_cleanup and then run 'rose' for the change to take effect. Rose / ClearCase Integration Instructions ========================================= Prior to starting Rose, make sure your PATH is set to include the PATH to the ClearCase executables. By default the ClearCase Add-In is not enabled. To enable the ClearCase Add-In, select Add-Ins:Add-In Manager. From the Add-In Manager dialog, select ClearCase and press OK. Adding "default.magic" "rose_unit" Information if using ClearCase 3.2.1 ------------------------------------------------------- If you are using ClearCase 3.2.1, it will be necessary to add Rose Unit file typing to your $ATRIA/config/magic/default.magic file *or* the *.magic file you use. If your Rose / ClearCase Integration is already setup (you have previously run "clearcase.sh setup -server" from a previous Rose for Unix release), please run (you may need to be root): rational_dir/releases/rose*/bin/clearcase.sh setup -magic_change This will save your original $ATRIA/config/magic/default.magic file as $ATRIA/config/magic/default.magic.rose.orig and will add the following necessary Rose Unit file typing information to $ATRIA/config/magic/default.magic: # Rose rose_model rose_unit rational source text_file : -name "*.mdl" ; petal rose_unit rational source text_file : -name "*.ptl" ; rose_package rose_unit rational source text_file : -name "*.cat" ; rose_component_diagram_package rose_unit rational source text_file : -name "*.sub" ; rose_properties rose_unit rational source text_file : -name "*.pty" ; rose_prp_properties rose_unit rational source text_file : -name "*.prp" ; rose_processor_diagram rose_unit rational source text_file : -name "*.prc" ; This file typing information should be added to any default *.magic file you use. Overview of Rose / ClearCase Integration Steps and Functionality ---------------------------------------------------------------- If you have not already completed the Rose / ClearCase Integration, refer to the following instructions. Rose includes a feature allowing you to select the following ClearCase options from the browser (right click on the element to see these options): - Add to Version Control - Check In - Checkout > Reserved - Checkout > Unreserved - Undo Checkout In addition, Merge and Compare operations are now performed by the Model Integrator. These operations may be performed on rose_unit's either within a Rose session via the ClearCase Browser or directly from ClearCase. Perform the following to activate this functionality: cd rational_dir/releases/rose.2002.05.00/bin If the Rose / ClearCase integration has already been set up, run: ./clearcase.sh setup -modelint_change This will recreate the Model Integrator (compare, merge, xcompare, xmerge) links in the $ATRIAMGRS/z_petal_file_delta type manager to point to the correct new release file (modelint_operations). You will see the following upon successful completion of this command: +++The type manager for Rose units has been reinstalled in the ClearCase server on this machine If the Rose / ClearCase integration has not already been set up, run: ./clearcase.sh setup -server This will create the $ATRIAMGRS/z_petal_file_delta type manager used to provide operations for rose_unit's, which will include the Model Integrator operations described above. The "-modelint_change" option may also be used upon uninstalling and installing a new version of Rose for Unix. Once a new version of Rose for Unix is installed, run the "clearcase.sh setup -modelint_change" command to recreate the Model Integrator links to point to the release file (modelint_operations) in the new installation location. Setting the ClearCase Path -------------------------- If ClearCase commands are not installed in the default /usr/atria location, you will need to edit the file "clearcase.sh". This file is located in: rational_dir/releases/rose.2002.05.00/addins/clearcase/bin Change the line "ATRIA=${ATRIAHOME:-/usr/atria}" to name the directory where ClearCase is installed, by replacing "/usr/atria" with your actual ClearCase installation path. If it is necessary to edit the clearcase.sh file in this manner, you will also need to make the same change to the following file: rational_dir/releases/rose.2002.05.00/bin/rose_mkdir Completing Rose / ClearCase Integration --------------------------------------- ** IMPORTANT NOTE ** You will need the appropriate directory permissions to write to $ATRIA/lib/mgrs on your server (when completing the setup described below, to add the necessary rose_unit type manager). Check the directory permissions in $ATRIA prior to running the Rose / ClearCase integration setup. If the Icon and File Typing rules for Rose units are to be included in the $ATRIA/config directory you will also need permission to write to this directory as well (see "", "" and "" in the "Rose / ClearCase Integration Requirements & How To Use "clearcase.sh"" section). Based on the permission levels in $ATRIA, you may need to be logged in as root to complete the Rose / ClearCase integration steps. Description of Rose Menu's Providing ClearCase Functionality ------------------------------------------------------------ When references are made to Rose menus (providing ClearCase options), the following describes which menus to use (based on the Rose Unit): Rose Unit Rose Menu ========= ========= *.mdl Tools > ClearCase *.cat Tools > ClearCase *.sub Tools > ClearCase Source Files Tools > ClearCase > Manage Generated Files In addition to the menus listed, a context menu option is available. The context menu offers a subset of the ClearCase options available in the menus listed above. Right clicking on an element in the browser will display a context menu which provides the selection of the following ClearCase options: - Add to Version Control - Check In - Checkout > Reserved - Checkout > Unreserved - Undo Checkout The steps in "Rose ClearCase Integration Steps" are in relation to Rose/ClearCase integration steps performed on Rose *.mdl files, as an example. Rose ClearCase Integration Steps -------------------------------- The following includes step by step instructions describing how to complete the Rose / ClearCase integration: 1. Either utilize an existing VOB or create a VOB where you wish to place elements, created by Rose. 2. Set your view, using the ClearCase command 'cleartool setview view-tag' in order to work with (have visibility to) the VOB defined in the previous step. 3. Invoke Rose. 4. Save the Rose unit (i.e.: *.mdl) in the VOB in which you wish to create Rose unit ClearCase elements. 5. Run either "clearcase.sh setup .." or "Tools > ClearCase > Setup [unit]'s VOB for Rose Units" -- You may either run 'clearcase.sh setup ..' as described in the section entitled "Rose / ClearCase Integration Requirements & How To Use "clearcase.sh"" below, or *Note: The option below, Select "Tools > ClearCase > Setup [unit]'s VOB for Rose Units" is only necessary if using ClearCase 3.2.1 or before or if you need to manage previously created "rose_unit" elements. "rose_unit" elements would be created by a Rose / ClearCase Integration, when using ClearCase 3.2.1 or before. -- Select "Tools > ClearCase > Setup [unit]'s VOB for Rose Units" This selection will install: -- Type Manager for Rose units to your ClearCase server on your machine -- Icon and File Typing rules for Rose units Selecting "Tools > ClearCase > Setup [unit]'s VOB for Rose Units" on a model which has been saved in a VOB, creates element type "rose_unit" for the *.mdl's VOB. A more complete explanation of the setup performed is included in the section entitled "Rose / ClearCase Overview and "clearcase.sh" Usage", below. Running either clearcase.sh or selecting the "Tools > ClearCase > Setup [unit]'s VOB for Rose Units" will perform the necessary steps to complete the Rose / ClearCase integration setup. Upon a successful Rose / ClearCase integration setup you should see the following types of messages. These messages will indicate that the type manager, icon and file typing rules have been applied to your server, and Rose units may be managed in your VOB: +++ The type manager for Rose units has been added to the ClearCase server on this machine +++ Icon and file typing rules for Rose units have been installed in .. Created element type "rose_unit". +++ Rose units may now be managed in VOB /vobs/vob_name/xx.mdl You should now be able to perform the available ClearCase commands on your Rose Unit from the following Rose menu options: Tools > ClearCase - for *.mdl, *.cat and *.sub units In addition to the menus listed, a context menu option is available. The context menu offers a subset of the ClearCase options available in the menus listed above. Right clicking on an element in the browser will display a context menu which provides the selection of the following ClearCase options: - Add to Version Control - Check In - Checkout > Reserved - Checkout > Unreserved - Undo Checkout ------------------------------------------------------------------ Common Integration Setup Error: ------------------------------- Listed below is a common error that may occur when attempting to perform the Rose / ClearCase integration setup or when attempting to use the Rose / ClearCase commands on Rose units. 1. mkdir: cannot access /usr/atria/lib/mgrs: Permission denied ***Can't create the Rose unit type manager on this machine. Greater access to /usr/atria/lib/mgrs may be required. Refer to the "IMPORTANT NOTE" under "Completing Rose / ClearCase Integration". You will need to run the setup as a user with the appropriate permissions in the $ATRIA/lib/mgrs directory. ------------------------------------------------------------------ Rose / ClearCase Overview and "clearcase.sh" Usage ================================================== The following describes the Rose / ClearCase integration requirements, how to use the "clearcase.sh" script designed to help perform the integration setup, general information in relation to ClearCase VOBs and Views, Controlled Elements as well as important information regarding View-Dependent Pathnames. Rose / ClearCase Integration Requirements & How To Use "clearcase.sh" --------------------------------------------------------------------- Rose units under ClearCase configuration management and version control use the user-defined element type "rose_unit". This element type must be defined in every VOB that contains a Rose unit. The type manager for rose_unit's must be installed on each server that manipulates such VOBs. Icons and filters for Rose units must be set up for each user that touches these Rose units under ClearCase. The "setup" subcommand of the clearcase.sh script provided in this release performs all three of these operations for a given user on a given VOB using a given server. The "setup" subcommand should be executed on each new instance of user, VOB, or server. Elements of type rose_unit cannot be created until this setup is complete. Your DISPLAY environment variable must be set prior to running clearcase.sh setup. If Rose units are not to be placed under ClearCase control, the "setup" subcommand does not need to be executed. Run clearcase.sh from the rational_dir/releases/rose.2002.05.00/bin directory. This will run a wrapper program designed to set up your environment prior to invoking the actual clearcase.sh script. The setup subcommand performs the following actions: 1. On the current server, creates and populates the directory for the rose_unit type manager: $ATRIA/lib/mgrs/z_petal_file_delta. 2. In an existing z_petal_file_delta type manager, changes compare, xcompare, merge, and xmerge operations to be performed by the Model Integrator. 3. In the VOB that is specified as the argument to the setup subcommand, the ClearCase element type is declared as "rose_unit" to be a supertype of compressed_text_file managed by the z_petal_file_delta type manager. 4. Sets up file and icon filters for Rose units by creating the following a. Creates a directory $ICONDIR, if it does not already exist, and creates the file "rose_unit.icon" in that directory b. Creates a directory $MAGICDIR, if it does not already exist, and creates the file "rose_unit.magic" in that directory c. Creates a directory $BITMAPDIR and copies "rose_unit.40" and "selected_rose_unit.40" into that directory. These three operations are controlled by the command-line syntax following the setup keyword: clearcase.sh setup [-user | -server " ..." | -default] [-icon ] [-bitmap ] [-magic ] "clearcase.sh" must be executed from: rational_dir/releases/rose.2002.05.00/bin A type manager is setup regardless of the parameters on the command line. If any VOBs are listed (for example, " ..."): clearcase.sh setup -server "/vobs/rose_model /vobs/.." the element type rose_unit will be defined in those VOBs. If any of the following options are specified, the icon and typing filters will be set up in the location specified by the options. is the directory in which the .icon file will be created. If -user is specified, it defaults to $HOME/.icon. If -server is specified, it defaults to $ATRIA/config/ui/icon. If -default is specified, it defaults to a value specified in the clearcase.sh scripts. is the directory in which the icon bitmaps will be created. If -user is specified, it defaults to $HOME/.bitmaps. If -server is specified, it defaults to $ATRIA/config/ui/bitmaps. If -default is specified, it defaults to a value specified in the clearcase.sh scripts. is the directory in which the .magic file will be created. If -user is specified, it defaults to $HOME/.magic. If -server is specified, it defaults to $ATRIA/config/magic. If -default is specified, it defaults to a value specified in the clearcase.sh scripts. In the released clearcase.sh script, the icon and typing directories are defined to be the same as the -server option, but an installer may edit the script to define these as preferred. ClearCase has three search paths, the icon file search path, the magic file search path, and the bitmap file search path. The default values for these search paths contain the directories defined by the -server and -user options to setup. If you use the ICON_PATH, BITMAP_PATH or MAGIC_PATH environment variables to override the default search path then you should use the -icon, -bitmap, and/or -magic options to specify a directory on your ICON_PATH, BITMAP_PATH, or MAGIC_PATH. Integration with Rose and ClearCase 4.x ======================================= ClearCase 4.x introduced formal support for Rose elements, by including a definition of Rose elements in the $ATRIA/config/magic/default.magic file as well as adding the $ATRIAMGRS/_rose type manager. If you have an existing Rose/ClearCase integration utilizing ClearCase 3.2.1 or before and you have updated your server to ClearCase 4.x, please note: o Existing Rose units have been created as "rose_unit" elements and will be managed by the $ATRIAMGRS/z_petal_file_delta type manager. (This was based on the original Rose/ClearCase integration, utilizing ClearCase 3.x.) o Newly created Rose units in the same VOB or a new VOB will be created as "rose" elements, managed by the $ATRIAMGRS/_rose type manager. (This is based on the availability of formal support for Rose elements in ClearCase 4.x.) o Running the setup as described above will accommodate both "rose_unit" and "rose" elements which may now exist in the same VOB (for the same type of Rose file, i.e. "*.mdl"). Both the "_rose" and "z_petal_file_delta" type manager will appear available to provide the necessary operations for both these elements. If you would like to convert the existing "rose_unit" elements to "rose" elements, you will need to run the following ClearCase command on each of the existing "rose_unit" elements: cleartool chtype rose [element_name].[rose_ext] VOBs and Views -------------- New VOBs and views are created and maintained in the usual way, outside of Rose. It is recommended that you set up ClearCase areas to hold your Rose units and code before using the Rose / ClearCase integration for the first time. Controlled Elements ------------------- The Rose / ClearCase integration provides operations on two kinds of elements: model units and code. Model (controlled) units are files in which Rose stores all or part of a model. Rose manages code files it has generated or reverse engineered. The operations for code files appear on the Tools > ClearCase > Manage Generated Files menu. When you set up Rose, a ClearCase element type, called "rose_unit" is declared for Rose units. rose_unit is a supertype of compressed_text_file. However, no ClearCase type is declared for code. We assume that each user will declare types appropriate for his or her code development environment. The Rose / ClearCase integration provides for differencing and merge operations utilizing the Model Integrator. (See the section regarding Merge and Compare operations in the beginning of this README for information describing how to activate this capability.) View-Dependent Pathnames ------------------------ Rose stores references to an element in a canonical form: as an absolute pathname that does not include any symbolic links, substituted where applicable by symbols from the path map. When you use ClearCase view-dependent names (/view//...), the references stored by Rose include the view information /view/. If you reference an element via a pathmap symbol, that symbol may not match properly if you use a view-dependent pathname. If you have a rule in your pathmap that includes an ampersand (&), the string substituted for the ampersand depends on the name used to load the referencing unit. For this version of the integration, it is best to not use view-dependent names if you use the pathmap, especially if you use a rule that contains an ampersand. The handling of view-dependent names may change in future versions of this integration. Removing the ClearCase Customization (Integration) ================================================== Refer to ClearCase Documentation in order to change elements which are currently 'rose_unit's and to remove the 'rose_unit' type manager. It is strongly recommended that a full backup is made, prior to performing these actions. Refer to special ClearCase instructions in relation to MULTISITED VOBs. -----------------------------------------------------------------------------