ClearCase/Guiffy with ClearCase type manager

by Guiffy customer Joerg Moeller

Disclaimer:
The following information and advice is given as to the best of my knowledge and has been carefully verified and tested. However, there's no guarantee that it works and of course no liability if it doesn't or if something really bad is happening. The information provided should be used by people who have at least a basic understanding of how ClearCase works. If you are not sure what the ClearCase commands will cause, please read the manuals. In order to ensure everything is in place and properly understood first steps should be done in a small test environment. A not properly installed/configured type manager will prevent people from getting they're work done. You want to avoid this (at least if your development folks are similar to mine ;-)

Why did you decide to use Guiffy instead of native ClearCase merge/compare tool?

We are using Objectime Developer as a CASE tool. Objectime Developer is the predecessor of Rose Realtime. The tool stores its model data in ASCII files. From these model files C++ code is generated. In order to have some synchronization capabilities between the tool and the file system the tool stores version information inside every model file. Every time a model file is checked out this data is modified. If more than one person is working on a file, conflicting version information inside these files occurs forcing them to resolve non-trivial conflicts in the merge tool. Actually not only the version of the file itself is stored but also version information about all referenced model files. If a lot of changes are done this causes hundreds of non-trivial merge conflicts and generates tons of work. To merge all of this non-trivial merge conflicts is very error prone and if one is messing up the syntax of the model files by adding two version lines, or removing both of them, the tool will just explode when opening the model without giving any hint which file is corrupted. After working a couple of years with this we finally decided to get the ClearCase/Objectime Developer interface straight. Unfortunately native ClearCase merge/compare tools aren't providing enough command line control. In order to get rid of the non-trivial merge conflicts we do some preprocessing first (basically remove all version information), then do the compare/merge with Guiffy and do some postprocessing afterwards (insert correct version information in the merged file).

Why would one like to use a ClearCase type manager in order to connect ClearCase with Guiffy?

If you don't want to use the compare/merge tools provided with ClearCase, you can always customize the context menu or write some Perl wrappers that will call a tool from another vendor. Unfortunately this doesn't work very well. Every time one is doing a merge or compare in the version tree browser for example the original ClearCase tool is popping up instead of the desired tool from another vendor. This is confusing and frustrating.

The only way to avoid this is to go to the guts of ClearCase and to implement a new type manager that'll use the new tool. With a type manager all CLI/GUI applications will automatically use the new tool for compare/merge actions.

Basically a type manager is just a "bridge" between a desired functionality and a proper (type specific) implementation. The compare and merge functionality are the most obvious type specific implementations to the user. Comparing two different version of plain ASCII files will result in a completly different compare tool as comparing two different version of a XML file.

How does ClearCase determine which type manager to use for a file and where's the link between a ClearCase type manager and ClearCase functionality?

Each file has an element type. It can be explored by right clicking on the file name and selecting "ClearCase\Properties of Element". Something like this box will appear:

As you can see the element type of the file is "text_file". The element type can easily be explored by right clicking the VOB and selecting "ClearCase\Explore Types", then select "element type":

The element type "text_file" is using the type manager "text_file_delta" which is based upon the type manager file.

The connection between type managers and the type specific implementation of these actions is done in a map file. It's located in "\Program Files\Rational\ClearCase\lib\mgrs". In the map file you'll find entries like this:

text_file_delta   create_element               ..\..\bin\tfdmgr.exe
text_file_delta   create_version               ..\..\bin\tfdmgr.exe
text_file_delta   delete_branches_versions     ..\..\bin\tfdmgr.exe
text_file_delta   compare                      ..\..\bin\cleardiff.exe
text_file_delta   xcompare                     ..\..\bin\cleardiffmrg.exe
text_file_delta   merge                        ..\..\bin\cleardiff.exe
text_file_delta   xmerge                       ..\..\bin\cleardiffmrg.exe
text_file_delta   annotate                     ..\..\bin\tfdmgr.exe
text_file_delta   get_cont_info                ..\..\bin\tfdmgr.exe

Each line consists of three parts. First is the type manager name, second is the ClearCase action and third is the path to the type specific implementation. A type manager doesn't need to implement all ClearCase actions. If a ClearCase action is missing the implementation of the type managers supertype will be used.

So what happens for example if one is checking out a version on a branch is that ClearCase determines the element type of the concerned file. The element type is connected with a type manager name. The type manager name and the chosen ClearCase action will be looked up in the map file and the executable where the map file is pointing to will be executed.

What else needs to be considered?

ClearCase type managers are host specific. A customized type manager needs to be installed on every client machine manually. Installing new ClearCase versions or patches could overwrite a customized type manger. If a new element type is used to introduce a new type manager on a replicated VOB the type manager needs to be available on the other sites, also.



How to install a ClearCase type manager for Guiffy

The necessary executables (their Perl sources) and map file additions are available for download from Guiffy.com at --- http://www.guiffy.com/download/guiffy_mgr.zip (2.49MB)

All you need to do is to copy the "guiffy_mgr" folder to "C:\Program Files\Rational\ClearCase\lib\mgrs" (or wherever your ClearCase installation is hosted. Please be aware of the fact that there is no splendid installation routine. If you have installed ClearCase in a different location you'll have to update all the paths in the Perl Scripts and recompile them.

The usage of the new Guiffy type manager can basically be introduced in two ways. First way would be to create a new element type that is connected with the Guiffy type manager and to change existing files to the new element type (don't forget edit the magic file in order to ensure that newly created files will be of new element type). Second way would be just to override the map file entries for an already existing type manager and to redirect the compare and merge actions to the Guiffy type manager implementations.

First way: Creating a new element type(recommended)

First: Create e new element type:

cleartool mkeltype -nc -supertype compressed_text_file -manager guiffy_mgr guiffy_file

Second: Convert all existing files to this new element type (assuming you want to change your c++ stuff):

cleartool find . -name '*.h' -exec 'cleartool chtype -force -nc guiffy_file %CLEARCASE_PN%'
cleartool find . -name '*.cpp' -exec 'cleartool chtype -force -nc guiffy_file %CLEARCASE_PN%'

Third: Open the map file from "C:\Program Files\Rational\ClearCase\lib\mgrs"

Make a copy of the type manager that implements the elements supertype of your Guiffy file element (compressed_text_file is the element type - z_text_file_delta is the type manager). Rename all the copied type manager lines from z_text_file_delta to guiffy_mgr. Let the compare, xcompare, merge and xmerge functionality point to the guiffy implementation.

Start with a copy of supertype type manager:

z_text_file_delta	construct_version		..\..\bin\ztfdmgr.exe
z_text_file_delta	create_branch			..\..\bin\ztfdmgr.exe
z_text_file_delta	create_element			..\..\bin\ztfdmgr.exe
z_text_file_delta	create_version			..\..\bin\ztfdmgr.exe
z_text_file_delta	delete_branches_versions	..\..\bin\ztfdmgr.exe
z_text_file_delta	compare				..\..\bin\cleardiff.exe
z_text_file_delta	xcompare			..\..\bin\cleardiffmrg.exe
z_text_file_delta	merge				..\..\bin\cleardiff.exe
z_text_file_delta	xmerge				..\..\bin\cleardiffmrg.exe
z_text_file_delta	annotate			..\..\bin\ztfdmgr.exe
z_text_file_delta	get_cont_info			..\..\bin\ztfdmgr.exe
Rename it to your type managers name:
guiffy_mgr	construct_version		..\..\bin\ztfdmgr.exe
guiffy_mgr	create_branch			..\..\bin\ztfdmgr.exe
guiffy_mgr	create_element			..\..\bin\ztfdmgr.exe
guiffy_mgr	create_version			..\..\bin\ztfdmgr.exe
guiffy_mgr	delete_branches_versions	..\..\bin\ztfdmgr.exe
guiffy_mgr	compare				..\..\bin\cleardiff.exe
guiffy_mgr	xcompare			..\..\bin\cleardiffmrg.exe
guiffy_mgr	merge				..\..\bin\cleardiff.exe
guiffy_mgr	xmerge				..\..\bin\cleardiffmrg.exe
guiffy_mgr	annotate			..\..\bin\ztfdmgr.exe
guiffy_mgr	get_cont_info			..\..\bin\ztfdmgr.exe
Let the diff, xdiff, merge and xmerge functionality point to the Guiffy implementation:
guiffy_mgr	construct_version		..\..\bin\ztfdmgr.exe
guiffy_mgr	create_branch			..\..\bin\ztfdmgr.exe
guiffy_mgr	create_element			..\..\bin\ztfdmgr.exe
guiffy_mgr	create_version			..\..\bin\ztfdmgr.exe
guiffy_mgr	delete_branches_versions	..\..\bin\ztfdmgr.exe
guiffy_mgr  compare     .\guiffy_mgr\guiffy_diff.exe
guiffy_mgr  xcompare    .\guiffy_mgr\guiffy_xdiff.exe
guiffy_mgr  merge       .\guiffy_mgr\guiffy_merge.exe
guiffy_mgr  xmerge      .\guiffy_mgr\guiffy_xmerge.exe
guiffy_mgr	annotate			..\..\bin\ztfdmgr.exe
guiffy_mgr	get_cont_info			..\..\bin\ztfdmgr.exe

or instead add these values to the registry:

Add a key: "\HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\TypeManagers"

Add a key: "\HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\TypeManagers\guiffy_mgr"

Below this key add values of type REG_SZ with the ClearCase action as name and the path to the executeable as value:
Name: "construct_version", Value "..\..\bin\ztfdmgr.exe"
Name: "create_branch", Value "..\..\bin\ztfdmgr.exe"
Name: "create_element", Value "..\..\bin\ztfdmgr.exe"
Name: "create_version", Value "..\..\bin\ztfdmgr.exe"
Name: "delete_branches_versions", Value "..\..\bin\ztfdmgr.exe"
Name: "compare", Value "..\..\bin\cleardiff.exe"
Name: "xcompare", Value "..\..\bin\cleardiffmrg.exe"
Name: "merge", Value "..\..\bin\cleardiff.exe"
Name: "xmerge", Value "..\..\bin\cleardiffmrg.exe"
Name: "compare", Value ".\guiffy_mgr\guiffy_diff.exe"
Name: "xcompare", Value ".\guiffy_mgr\guiffy_xdiff.exe"
Name: "merge", Value ".\guiffy_mgr\guiffy_merge.exe"
Name: "xmerge", Value ".\guiffy_mgr\guiffy_xmerge.exe"
Name: "annotate", Value "..\..\bin\ztfdmgr.exe"
Name: "get_cont_info", Value "..\..\bin\ztfdmgr.exe"

This way has been suggested by Rational support (it's not officially supported and not guaranteed to work in future versions). The good news is that these registry information won't be overwritten by new ClearCase versions or patches like the map file.

Fourth:
Edit default.magic file in "C:\Program Files\Rational\ClearCase\config\magic" in order to ensure that newly created files will be of element type "guiffy_file".

Second way: Overriding existing type manager (not tested and not recommended)

Get the element type(s) of the files you want to send to Guiffy. Get the type managers that are used in these element types. Open the map file from "C:\Program Files\Rational\ClearCase\lib\mgrs" and let each type managers compare, xcompare, merge and xmerge point to the Guiffy implementation (modified in blue).

Example:

text_file_delta   construct_version            ..\..\bin\tfdmgr.exe
text_file_delta   create_branch                ..\..\bin\tfdmgr.exe
text_file_delta   create_element               ..\..\bin\tfdmgr.exe
text_file_delta   create_version               ..\..\bin\tfdmgr.exe
text_file_delta   delete_branches_versions     ..\..\bin\tfdmgr.exe
text_file_delta   compare                 .\guiffy_mgr\guiffy_diff.exe
text_file_delta   xcompare                .\guiffy_mgr\guiffy_xdiff.exe
text_file_delta   merge                   .\guiffy_mgr\guiffy_merge.exe
text_file_delta   xmerge                  .\guiffy_mgr\guiffy_xmerge.exe
text_file_delta   annotate                     ..\..\bin\tfdmgr.exe
text_file_delta   get_cont_info                ..\..\bin\tfdmgr.exe

Instead of editing the map file this also can be done via the registry like describe above. Just create an entry with the type managers name and add values for the compare, xcompare, merge and xmerge.

Please consider that these changes will effect any (!) file that is connected with this type manager. There may be more then one element types connected with this type manager. Since type managers can be based upon other type managers you may also change the behavior of subtypes of the modified type manager. This is a real quick and dirty solution! Don't try it if you aren't really sure what will happen!



The Guiffy type manager

Basically the Guiffy type manager implementation is just parsing the ClearCase arguments and passing them to the Guiffy tool and providing proper return values to ClearCase. The difference between compare and xcompare (merge and xmerge respectively) is that compare is the command line version of compare while xcompare the GUI version is. I wasn't eager to spend too much time in the command line versions (especially not for the merge functionality) so the Guiffy compare output isn't reformatted to look like the output ClearCase would generate and there's no command line merge functionality. If a non-trivial merge is detected on the command line the GUI tool will pop up. Where possible ClearCase settings are passed to Guiffy. If Guiffy doesn't provide similar functionality the option is simply ignored. Where ClearCase is missing functionality that Guiffy provides registry values or environment variables can be used to configure the environment (treatment of white spaces for example). Using the ClearCase -blank_ignore option will overwrite the settings that have been made in the registry or in environment variables.

If you want to go with the registry please create a key "\HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\Guiffy"

Below this key create the values as listed in the following table. When you're done it should look like this:

These options can be passed to Guiffy by defining registry values or environment variables:

Command line option Meaning Environment variable Registry value
-c ignore upper/lower case differences GUIFFY_IGNORE_CASE IgnoreCase (1 - ignore case)
-ed, -em, -eu eol written for Dos, Mac or Unix GUIFFY_EOL (with value DOS, MAC or UNIX) Eol (with value DOS, MAC or UNIX)
-k ignore blank lines GUIFFY_IGNORE_BLANK IgnoreBlank (1 - ignore blank)
-w ignore white space differences GUIFFY_IGNORE_WHITESPACE IgnoreWhiteSpace ( 1 - ignore Space)
-gs no result file when conflicts GUIFFY_NO_RESULT_WHEN_CONFLICT (if defined no file is generated when conflict occurs) NoResultWhenConflict ( 1 - no file is generated when conflict occurs)

The type manager first looks for registry values then for environment variables. If nothing is found default values are used.

Command line option Meaning Default value
-c ignore upper/lower case differences 0
-ed, -em, -eu eol written for Dos, Mac or Unix DOS
-k ignore blank lines 1
-w ignore white space differences 1
-gs no result file when conflicts 1



How to extend the Guiffy type manager

The provided Guiffy type manager is just a very basic implementation. If you need a more type specific implementation you can use the Perl scripts as a starting point. I didn't manage to run the native perl scripts with a perl interpreter (but I didn't try very hard). I would recommend to convert the Perl scripts into an executeable. This can easily be done with the Activestate Perl development kit.

The ClearCase::CtCmd module can be found at CPAN.



Problems, questions, contact

If you encounter problems please, fix them ;-) You can also report them to me. If you are lucky I'll fix it, if you are not lucky you'll fix it. If you have any question or comments don't hesitate to contact me at JoergMoeller@gmx.de.