ClearCase keyword substitutions merge manager

A utility to implement keyword expansion in ClearCase

Many SCM products use a feature called "keyword substitution," or "keyword expansion" as a way of identifying files under version control. This script enables this feature in IBM Rational ClearCase.

Share:

Daniel Diebolt (dida@ch.ibm.com), Senior ClearCase consultant, IBM Rational

Daniel Diebolt is a Senior Technical Representative with IBM in Switzerland, specializing in Rational software.



13 December 2005

NOTE: These scripts have only been tested on Windows systems, and not on UNIX or heterogenous environments.

Introduction

IBM Rational® ClearCase® is a Software Configuration Management (SCM) tool. ClearCase has been available for more than 10 years, and works on both the UNIX® and Windows® platforms, as well as heterogeneous environments. ClearCase has powerful command line interface and triggering functionalities, and can be easily customized to the needs of end users.

Unified Change Management (UCM) implements on top of ClearCase (and optionally IBM Rational ClearQuest), and provides a process workflow that dramatically simplifies parallel development.

Other SCM tools, such as Revision Control System or RCS, implement a feature called "keyword substitution," or "keyword expansion" as a way of identifying files that are added to source code over version control. These keywords are automatically updated during the checkout / checkin process. ClearCase does not implement this feature out of the box, and neither is it provided by UCM. The purpose of this document is to describe the necessary steps to install and use a new keyword substitution merge manager for ClearCase.

Example of such keywords are as follows:

  • $Author:$
  • $Date:$
  • $Header:$
  • $Id:$
  • $Name:$
  • $Revision:$
  • $Source:$

Example of usage in a file called test.c:

/*
	$Author: ccadmin $
	$Date: 2005-08-17 12:46:00 GMT $
	$Header: @(#) \test_vob\test.c@@\main\1  2005-08-17 12:46:00 GMT  ccadmin $
	$Id: @(#) test.c@@\main\1  2005-08-17 12:46:00 GMT  ccadmin $
	$Name: test.c $
	$Revision: \main\1 $
	$Source: \test_vob\test.c $
*/

ClearCase version

ClearCase v2003.06.14 has been used in this document, as shown in the following output:

C:\>cleartool -ver
ClearCase version 2003.06.00 (Fri Apr 18 13:06:18 2003)
clearcase patch p2003.06.01 (Fri Sep 5 11:59:28 2003)
clearcase patch p2003.06.12 (Fri Nov 7 11:59:28 2003)
@(#) MVFS version 2003.06.10+ (Nov 12 2004 09:49:18)
cleartool                         2003.06.10+ (Mon Nov 15 21:06:24  2004)
db_server                         2003.06.10+ (Fri Nov 12 09:03:18  2004)
VOB database schema version: 54

C:\>cleartool -verAll
ClearCase version 2003.06.00 (Fri Apr 18 13:06:18 2003)
clearcase patch p2003.06.01 (Fri Sep 5 11:59:28 2003)
clearcase patch p2003.06.12 (Fri Nov 7 11:59:28 2003)
@(#) MVFS version 2003.06.10+ (Nov 12 2004 09:49:18)
cleartool                         2003.06.10+ (Mon Nov 15 21:06:24  2004)
libatriaadm                       2003.06.10+ (Fri Nov 12 07:50:08  2004)
libatriaccfs                      2003.06.10 (Thu May 22 02:26:37  2003)
libatriaclient_meters             2003.06.10+ (Fri Nov 12 08:12:29  2004)
libatriacm                        2003.06.10+ (Fri Nov 12 07:56:01  2004)
libatriacmd                       2003.06.10+ (Fri Nov 12 08:14:24  2004)
libatriacmdsyn                    2003.06.10+ (Fri Nov 12 08:15:37  2004)
libatriacredmap                   2003.06.10+ (Wed Jun 23 07:43:55  2004)
libatriadbrpc                     2003.06.10+ (Fri Nov 12 07:55:20  2004)
libatriaks                        2003.06.10+ (Fri Nov 12 07:47:23  2004)
libatriamntrpc                    2003.06.10+ (Fri Nov 12 08:16:22  2004)
libatriamsadm                     2003.06.10+ (Fri Nov 12 07:46:51  2004)
libatriamvfs                      2003.06.10 (Sat Apr 12 20:49:57  2003)
libatriasplit                     2003.06.10+ (Fri Nov 12 08:08:47  2004)
libatriasum                       2003.06.10+ (Tue Nov  2 08:03:34  2004)
libatriasumcmd                    2003.06.10+ (Fri Nov 12 08:11:08  2004)
libatriatbs                       2003.06.10+ (Fri Nov 12 07:48:58  2004)
libatriatool                      2003.06.10+ (Fri Nov 12 08:08:36  2004)
libatriaview                      2003.06.10+ (Fri Nov 12 08:08:02  2004)
libatriavob                       2003.06.10+ (Wed Dec 15 19:36:09  2004)
libatriaxdr                       2003.06.10+ (Fri Nov 12 07:50:32  2004)
db_server                         2003.06.10+ (Fri Nov 12 09:03:18  2004)
VOB database schema version: 54

Acknowledgements

Special thanks go to:

  • Stephen Gildea and David Kaelbling, first writers of the type manager
  • Joerg Svensson (SVENSSON@de.ibm.com), who update the source code to make it work on ClearCase v2003.06
  • ClearCase Team by Draeger (Germany), who requested this feature integrated into UCM

Implementation concept

ClearCase has a type manager interface to implement ClearCase commands (such as, create version, merge, compare, etc.). This makes it easy to change some of the default behavior of ClearCase.

Here we are writing our own type manager, that is invoked over the compare and merge operation in ClearCase. The type manager simply stores in some temporary place the version information, without the keyword substitution.

Installation

In addition to these instruction you will need the following files:

Table 1. List of merge manager files
File nameDescription
c.batCopy script
m.batCompilation script
md.batCompilation script (debug mode)
manager.cSource of the type manager
keyword_subst.plTrigger to use
  1. Copy all the files listed above to a directory called c:\keyword
  2. Edit the md.bat file and the m.bat to adjust the path to the vcvars32.bat (Microsoft Visual C++ compiler settings) and ClearCase installation directory paths
  3. Compile the manager.exe program, by calling either m.bat or md.bat (debug mode). You should get a file created called manager.exe

Copying the type manager

  1. Edit the c.bat file to adjust the path to the ClearCase installation directory
  2. Launch c.bat to copy manager.exe to %CLEARCASEHOME%\bin, as ktfdcompare.exe

Warning: You need to copy the new type manager to all the ClearCase clients and to the view server.

Modifying the map file

Edit the file c:\Program Files\Rational\ClearCase\lib\mgrs\map, and add the following:

keyed_text_file_delta		construct_version		..\..\bin\tfdmgr.exe
keyed_text_file_delta		create_branch			..\..\bin\tfdmgr.exe
keyed_text_file_delta		create_element			..\..\bin\tfdmgr.exe
keyed_text_file_delta		create_version			..\..\bin\tfdmgr.exe
keyed_text_file_delta		delete_branches_versions	..\..\bin\tfdmgr.exe
keyed_text_file_delta		compare				..\..\bin\ktfdcompare.exe
keyed_text_file_delta		xcompare			..\..\bin\ktfdcompare.exe
keyed_text_file_delta		merge				..\..\bin\ktfdcompare.exe
keyed_text_file_delta		xmerge				..\..\bin\ktfdcompare.exe
keyed_text_file_delta		annotate			..\..\bin\tfdmgr.exe
keyed_text_file_delta		get_cont_info			..\..\bin\tfdmgr.exe

Trigger

Copy the keyword_subst.pl perl script to a common storage area for ClearCase triggers (for example, to a share on the server).

Usage

Element type

For each VOB that you want to use the new type manager, you need to create a new element type: cleartool mkeltype -supertype text_file -manager keyed_text_file_delta -c "RCS keyword type" eltype:keyed_text_file@vob:<your-vob>

Example: M:\test_view\test_vob>cleartool mkeltype -supertype text_file -manager keyed_text_file_delta -c "RCS keyword type" eltype:keyed_text_file@vob:\test_vob Created element type "keyed_text_file"

Adjustment of elements

For each VOB that you want to use the new type manager, you need to create a new trigger type: cleartool mktrtype -element -all -preop checkin -eltype keyed_text_file -execwin "ccperl \\<server>\<trigger_share>\keyword_subst.pl" KEYWORDSUBST

Example: M:\test_view\test_vob>cleartool mktrtype -element -all -preop checkin -eltype keyed_text_file -execwin "ccperl \\titeuf\keyword\keyword_subst.pl" KEYWORDSUBST@\test_vob Created trigger type "KEYWORDSUBST"

Adjustment of the element type

For all the elements that you want to use the new element type, enter: cleartool chtype keyed_text_file <element_name>

Example: M:\test_view\test_vob>cleartool chtype keyed_text_file test.txt
Change version manager and reconstruct all versions for "test.txt"? [no] yes
Changed type of element "test.txt" to "keyed_text_file"

Usage over compare

Over a compare, you should get the file diffs without any keyword substitution, as shown in Figure 1:

Figure 1. Comparing versions
version comparison

Usage over merge (and deliver/rebase)

Over a merge (e.g. deliver and rebase), you should get the file diffs without any keyword substitution, as shown in Figure 2:

Figure 2. Merging versions
version merging

Further considerations

With this small utility, you can easily implement keyword substitution in ClearCase without any trouble, but it should be noted that:

  • This has not been tested on UNIX
  • The following RCS keywords are not supported: Log, Locker
  • Line of source cannot be bigger then 8192 characters.

Download

DescriptionNameSize
Sample Perl scripts for this articlecc_merge_manager.zip44KB

Resources

Learn

Get products and technologies

  • Find more resources for ClearCase users and administrators in the ClearCase area of the developerWorks Rational zone, including articles and whitepapers, plug-ins, scripts and triggers; and links to training, discussion forums, product documentation and support.
  • To learn more about IBM Rational products, visit the developerWorks Rational zone. You'll find technical documentation, how-to articles, education, downloads, product information, and more.

Discuss

  • Find a user group in your area from the Rational Global User Group Community. Rational User Groups are independent, user-run organizations that provide an open forum to promote information exchange between customers and Rational staff.
  • The ClearCase discussion forum on developerWorks is a great place to post questions and get answers about configuration management and UCM with IBM Rational ClearCase.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=100163
ArticleTitle=ClearCase keyword substitutions merge manager
publish-date=12132005