I am often asked why ClearCase does not automatically perform "Keyword substitution or expansion". That I can't answer, but I can say that I was never a big proponent of inserting meta-data into source files, that already have the meta-data associated through ClearCase that is easily readable with cleartool commands like find, ls, desc and others; I have seen to many files in my time where the inserted meta-data gets significantly larger over time than the "meat" of the file (i.e. when meta-data like comments are prepended to source files). An exception to my dislike is when the keyword meta-data is used to identify "post release" items. RCS-type keyword substitution can be useful in determining the identity of an executable or the file used to build it after the product has left CM control and reached the field or user base.
"What many have trouble with is not the required trigger that performs the 'insertion' or 'expansion' of the keywords during checkin, but rather the pain and added complexity it can cause for developer merges and deliveries if the trigger is not supported by an underlying 'keyword aware' type_manager." Some other SCM products (i.e. RCS) natively implement "keyword expansion" (also known as "keyword substitution") such that by viewing embedded data one can identify an item even after it has have left CM control and has been delivered to the field. This functionality does not exist in ClearCase as of version v2003.06, but can be easily implemented by creating a custom type manager and an associated. I say easy because how to do so is outlined in this document and the associated code is also included here. There are two (2) necessary steps to properly facilitate "keyword expansion" in ClearCase:
1) Create a pre-op checkin trigger that "expands/updates" the keywords in created source code. 2) Create a type_manager that ignores these keywords during ClearCase Compare and Merge functions.
The first step (the pre-op checkin trigger) is not too difficult and I have seen many such script that do the job, but they eventually fall out-of-favor with developers and are not used because they increase the complexity of merges and compares as often times only the keyword values themselves are changed in the file and for the ClearCase compare/merge facilities they are indistinguishable from developer changes and as such remove any possibility of a trivial merges during parallel development. You can use and modify the pre-op checkin trigger (KEYWORD_MGR.pl located in the "Triggers" of the ClearWeb Developer Network) we have provided or create your own. KEYWORD_MGR.pl is quite robust and is used in several organizations worldwide. The second step (the type_manager) is a bit harder to implement (but not for you since it is included) as it requires a more intimate knowledge of ClearCase. The key is to create a construct that traps all compare and merge functions in ClearCase and "swap" out the actual files to be used with equivalent files that have there keywords "suppressed" so that the keywords themselves are ignored in the comparison or merge. Files that are only different because of their keywords are in affect "identical" files to ClearCase. The type_manager (keyword_mgr.c) and installation instructions are available in the "Wrappers" section of the ClearWeb Developer Network. The result is to get "Keyword expansion/substitution" without adversely affecting developer merges and deliveries: For example, for two version of foo.c (version /main/int/4 and /main/int/fea/1) that both have the keywords:
/* $Author:$ $Date:$ $Revision:$ $Source:$ */
such that their complete file versions are depicted below:
|
foo.c
|
|
version: /main/int/4
|
version: /main/int/fea/1
|
|
/* $Author: vobadm $ $Date: 2005-10-12 12:00:00 GMT $ $Revision: /main/int/4 $ $Source: /vobs/a_vob/foo.c $ */ int main (int argc, char ** argv) { char hello[] = "hello";
printf ("%s", hello);
exit (0); }
|
/* $Author: vobadm $ $Date: 2005-10-14 12:05:50 GMT $ $Revision: /main/int/fea/1 $ $Source: /vobs/a_vob/foo.c $ */ int main (int argc, char ** argv) { char hello[] = "hello";
printf ("%s", hello);
printf (" world!\n");
exit (0); }
|
If you just have the trigger implemented the new versions have the correct embedded information in them, but in this case (and several others) the keywords changes themselves would not allow ClearCase to perform the "trivial" merge (which this would be if not for the keywords) from the "fea" branch to the "int" branch. Without the type_manager those keywords changes are treated as development changes for merges and compares. and developer will have to manually accept the conflicting changes. With type_manager enabled the keywords in the contributing versions (for compare or merge operations) are suppressed first so only actual development changes are evaluated resulting in the desired trivial merge which ClearCase can do itself.
|
foo.c
|
|
version: /main/int/4
|
version: /main/int/fea/1
|
|
/* $Author:$ $Date:$ $Revision:$ $Source:$ */ int main (int argc, char ** argv) { char hello[] = "hello"; printf ("%s", hello); exit (0); }
|
/* $Author:$ $Date:$ $Revision:$ $Source:$ */ int main (int argc, char ** argv) { char hello[] = "hello"; printf ("%s", hello); printf (" world!\n"); exit (0); }
|
Once the merge is complete, checkin in the file creates a new version (/main/int/5) with the development changes as well as the new expanded keyword data which is automatically expanded with the pre_checkin trigger KEYWORD_MGR.pl.
|
foo.c version: /main/int/5
|
|
/* $Author: vobadm $ $Date: 2005-10-14 12:15:51 GMT $ $Revision: /main/int/5 $ $Source: /vobs/a_vob/foo.c $ */ int main (int argc, char ** argv) { char hello[] = "hello"; printf ("%s", hello); printf (" world!\n"); exit (0); }
|
Implementation
You can get full details on implementation (including all source code) for both the trigger KEYWORD_MGR.pl (located in the "Triggers" of the ClearWeb Developer Network) and the type_manager keyword_mgr.c (available in the "Wrappers" section). You will see it is not hard when you know how..
Charles Clarke III is President of A Better Solution, Inc. With over 20 years of professional IT experience as both a software developer and CM Professional, he saw the need for a CM consulting company from his early experiences with Atria (the original makers of ClearCase). To this end he has assembled some of the best software minds in the country to bring the experiences of many minds in many development shops together to aid in the implementation of ClearCase. He was the software architect of some of the most successful ClearCase add-on tools, ClearTrigger, ClearReplica, ClearWeb and ClearManage. ABS provides consulting, tools and training to suit an organizations needs for ClearCase. Visit http://www.abs-consulting.com for more details.
Trackback(0)
 |
TrackBack URI for this entry
Subscribe to this comment's feed
