Using ClearCase

Contents

• Conventions
• Getting Started
  • Unix
  • Windows NT
• Operations used by Developers
  • Getting Help
  • Checkouts and Checkings
  • Bringovers, Putbacks and Merges
  • Troubleshooting

Introduction

The clearcase development model used at this location is a simple parallel development model:

• There is a release branch for every targeted release.
• There is a release view associated with every release branch.
• There is a build snapshot view associated with every release branch
• Every developer will have one or more development branches which target a specific release branch.
• Every development branch will have a unix development view and/or an NT development view associated with it.

The following naming conventions will be used:

• Release branch names begin with a lower case letter and are followed by lower case letters or numbers.
• Release branch names must be prefixed with the name of the project who owns them.
• Development branches look like this: releasebranch_userid[_string]. If the same developer is using multiple branches for the same release branch, an additional identifier may be appended.
• Release views are named after the release branch they are configured to select.
• Development view names look like this: developmentbranch[_nt|_snapshot]. The _nt indicates that msdos text mode is on and that the view is intended to be used on NT workstations. The _snapshot indicated that the view is hosted by an NT workstation and is a development snapshot view.
• Unix only development views shall not be registered in the sf_nt region. NT snapshot views shall not be registered in the sf_unix region.

Getting Started

Unix

1. Use the uname -sr command to ensurethat you have at SunOS5.6 installed on your workstation.
2. Use the id command to ensure that your currently active group is rapsdev. Use newgrp rapsdev if this is not the case. You cannot use clearcase if you are not member of the rapsdev group.
3. Goto /ccase/release/v3.21/sun5/install.
4. Run ./install_release.
5. Choose 1 (local install).
6. Choose 4 (link only install).
7. Accept the suggested defaults for all questions concerning locations of things.
8. Choose 7 (clearcase full function install), then f (finish).
9. Accept the suggested defaults for the remaining questions. Wait for completion of the installation. No reboot is necessary.
10. Ensure you have /usr/atria/bin in your PATH. Rehash.
11. Say cleartool mount -a. This mounts all the VOBs.
12. Say ct_mkview releasebranch_userid. This will create your development branch and your unix development view.
13. Say cleartool setview releasebranch_userid.
14. You now may start checking out files for development.

./install_release also takes command line options:
-comp = components
-model = install model
-lh = license host
-rh = registry host
-rr = region
-to = install destination (ie. /usr/atria)
-from = central install area
-local (do local install)

Windows NT

Please follw these instructions step by step and make sure you don't skip a step. NT is a buggy, weird piece of $%#^ and will give very obscure error messages if any of the following steps are not executed properly.

1. Make sure you have windows NT4.0 with service pack 3 installed.
2. Make sure you have at least 300 MB on your C: drive.
3. Make sure you are logged onto the RESOLUTE_MAIN domain and that you have local administrator priviledges.
4. Goto Settings>ControlPanel>System>Environment. Make sure that your TEMP and TMP System Variables are set to a local drive. Add a User Variable called CLEARCASE_PRIMARY_GROUP and give it the value rapsdev.
5. Goto Network Neighbourhood\Castor\ccase\release\v3.21\nt and double click on setup.exe
6. Accept all defaults and wait until install finishes. Allow it to reboot the machine (long live NT).
7. While NT is rebooting, log onto a UNIX workstation. Make sure your current group is rapsdev. Use the newgrp rapsdev command if it isn't.
8. Say ct_mkview releasebranch_userid_nt. This will create your development branch and your NT development view.
9. After the reboot, log on as yourself in the RESOLUTE_MAIN domain and go to Settings>ControlPanel>ClearCase>MVFS Performance. Override the Mnodes settings by entering 800 instead of the default 1800. This is so that you do not overload the smb server on the UNIX side (samba).
10. On your NT workstation, click on the "clearcase home" icon on your desktop.
11. Select the "Administration" tab.
12. Click on the "Region Synchronizer" button.
13. Select the view called releasebranch_userid_nt (the one you just created on the UNIX machine).
14. Click on the "Import..." button.
15. In the dialog box with all the view specific data, make sure that the "Global Storage Path" is \\castor\ccase\viewstore\releasebranch_userid_nt. It often pops up erroneously as \\castor\export\ccase\viewstore\releasebranch_userid_nt. You need to take string export out of the path. Click on OK once you verified this.
16. In the Clearcase home base, select the "Views" tag.
17. Click on the "Start View" button.
18. Locate your view (releasebranch_userid_nt), choose a drive letter and click on OK.
19. In the Clearcase home base, select the "VOBs" tag.
20. Click on the "Mount VOB" button.
21. Select all the VOBs and click on "Mount".
22. You should now be set. You can use the ClearCase details button under the "Elements and Versions" tab in the clearcase home base to browse through all the elements.

Operations used by Developers

Getting Help

Besides looking at the User's Guide and Reference Manual, there are two forms of online help:

cleartool help subcommand

This gives you a short synopsis of the subcommand and its options.

cleartool man subcommand

This will give you the exact text of the reference manual page for the given subcommand.

You can also use the Web Interface to the clearcase and UNIX man pages.

Checkouts and Checkins

The basic commands for these operations are:

cleartool co element name

to check out a file;

cleartool ci element name

to check a file back in;

cleartool unco element name

to cancel a checkout;

cleartool mkelem -ci filename

to put an existing file under version control - remember to check out the containing directory;

cleartool mkdir dirname

to create a version controlled directory - remember that the containing directory must be checked out;

cleartool mv from to

to rename or relocate a version controlled element - both the source directory and the target directory must be checked out;

cleartool rm element name

to remove an element - the containing directory must be checked out. Note that you can easily remove a whole subtree this way...

Some of the commands above will prompt you for a comment. You can turn this off by placing a file named .clearcase_profile in your home directory. The recommended content of this file is:

# This file should be placed in $HOME/.clearcase_profile
 
checkin  -cqe    # prompt for comment on every argument of checkin.
*        -nc     # no comment required for all other operations.

Bringovers, Putbacks and Merges

All of these operations require that you have checked in all your files. The operations will tell you which files you haven't checked in.

The following is just an overview. Please refer to the Wrapper Script Reference for an in depth discussion of the following scripts and their options.

ct_bringover [-g] [-debug] [pname ...] [-from branch]

This operation will synch up your development branch with the newest from the release branch. You might need to do merges. In detail, this operation does the following:

• Check if the release view is running
• Update the config spec of your development view so that it sees the latest versions on the release branch
• Check if there are checked out files
• lock the release branch and your development branch
• perform merges, warning you about those that it can't do automatically
• List those elements which have been merged
• unlock the release and development branches

Should merges be required, an attempt will be made to resolve them automatically. If the merges cannot be resolved automatically, a message will be shown together with a list of commands which will allow the user to resolve the merges interactivly.

ct_putback [-g] [-debug] [-keep] [-preview|-n] [-fixed bugid[,bugid...]] [-c 'putback comment'] [pname ...]

This operation will make your changes visible to other developers by merging them into the release branch. It is important that this merge be a trivial merge (i.e. simply a matter of replacing the old version with your new version). The operation will use a heuristic based upon the way config specs are used to predict whether the merges will be trivial or not. In detail:

• Check if the release view is running.
• Compare the version of a history file as seen by your development view with the version as seen by the release view. If they are different, then there is an inference that someone else did a putback since your last bringover, and that you need to run a bringover prior to this putback.
• Look for checked out files.
• Query the user for a list of bugs fixed by this putback and an overall putback comment -- unless -preview is specified on the command line.
• Lock the development and release branches.
• perform the directory merges.
• perform the file merges.
• Check for merge conflicts. If there are any, undo the merge and exit.
• locate the checked out files in the release view. These are the files that have been put back.
• For every one of those files, collect the comments from the event records since the last bringover and make that the checkin comment in the release view.
• Create hyperlinks from the history file to the merged files.
• Update the history file.
• Release locks on the development and release branches.
• Send email to all developers with the collected checkin comments.

Troubleshooting Guide

The following failure modes are in the "should not happen" category, but people do break things... Please always send a bug report to cmadmin@digisle.net if you feel that some script, wrapper or trigger failed to produce a correct result.

bringover/putback aborts

If for some reason the ct_bringover or ct_putback fails, you can try to run it again after fixing the problem that caused the failure. Both commands should be able to recover from a previous failure.

If you aborted a putback while entering a putback comment, you should manually release the locks or redo the putback as soon as possible. Note that nobody else can do bringovers or putbacks while you have a putback lock on a particular release branch.

Breaking Locks

If you suspect that someone else's bringover or putback failed and nothing is being done to fix the situation, you can break the lock with /ccase/wrapper/ct_unlock branchname.

Note that arbitrarily breaking locks may corrupt the history file and produce an inconsistent combination of versions on the release branch, so care should be taken to find out why a lock needs to be broken.

When breaking a putback lock, verify that the /view/branchname/vob/history/history file is checked in. If it is checked out, cancel the checkout prior to breaking the lock.