Views
How many Views do I need?
Generally, one per discrete task is a good idea, though this is not a requirement. Views should be regarded as "cheap" entities that are easily created and destroyed. Create one for each task you need to do and when that task is done, delete the view.
Dynamic versus Snapshot Views
ClearCase and ClearCase LT offer snapshot views as workspaces. Snapshot views work by copying versions of elements from VOBs to your computer. To see the latest versions of elements, you need to update your snapshot view periodically. An update operation copies the latest versions of elements from the VOB to your view.
ClearCase (but not ClearCase LT) also offers dynamic views. A dynamic view uses the Multiversion File System (MVFS) to provide immediate, transparent access to data stored in VOBs. When you work in a dynamic view, you do not need to copy data fromVOBs to your view; you always see the latest versions of elements. Dynamic views also provide advanced functionality such as build auditing and binary sharing.
How to create a Dynamic View
cleartool mkview -tag atag storage-location
Where atag is the view-tag (the "name" of the view which should be a name that you can easily remember) and storage-location is the location of a place on a disk where the view can store information.
Alternatively, there is a simplified command:
cleartool mkview -tag atag -stgloc -auto
In this example, you don't need to specify a storage location, but rather this command enables you to use a storage location that has been set up by your ClearCase admin.
How to delete a Dynamic View
cleartool rmview -tag atag
Where atag is the view-tag of the view you want to remove.
How to create a Snapshot View
cleartool mkview -snapshot -tag atag -stgloc -auto apathname
Where apathname is the path to which you want your source code (work area) to reside. The -tag atag is optional - if you omit it, ClearCase will make one up based on your username and the workspace you specify in apathname.
How to delete a Snapshot View
cleartool rmview apathname
Where apathname is the path to where your source code (work area) resides.
.
Modifying files
Checkout
To modify an element you need to check it out. Do this with the following command:
cleartool co anelement
where anelement is the name of the file or directory you want to check out.
Checkin
Once you are happy with the changes you have made to a checked-out element, you can check it in with the following command:
cleartool ci anelement
where anelement is the name of the file or directory you want to check in. Once you check-in an element, the changes you made to that element are usable by everyone on your project.
Uncheckout
If you want to cancel a checkout, you can do so with the following command:
cleartool unco anelement
where anelement is the name of the file or directory you want to check in.
.
Creating new files
Creation
To create a new file, you can use whatever editor or command you would normally use to create the file. The new file will be a view-private entity until you take the next step to put it under ClearCase control.
Putting a file under version control
To put a file under ClearCase control you must first check-out the directory that will be containing the file, issue the command to tell ClearCase to put the file under version control, and then check-in the directory containing the new file. Here are commands to perform these steps:
cleartool co thedirectory
cleartool mkelem thefile
cleartool ci thedirectory
After this sequence is performed, the file thefile is still checked-out and can be modified further before you check it in.
.
Deleting elements
To remove an element you should use the cleartool rmname command. This command removes the name of the specified element from the directory in which it is contained. Similar to placing an element under ClearCase control, you must first check-out the directory containing the element to be removed, do the cleartool rmname of the element, and then check-in the new version of the directory. Here is an example:
cleartool co thedirectory
cleartool rmname anelement
cleartool ci thedirectory
After this sequence, anelement is no longer listed in subsequent versions of thedirectory. It is, however, still listed in previous versions of the directory. If, at a later date you want to re-add anelement to a new version of thedirectory (or any other directory), you can do so easily.
.
Renaming elements
Renaming an element is similar to deleting it. First you check-out the old directory containing the element, and you also check-out the new directory to which the element is to be moved. Then you use the cleartool mv command to perform the move operation. Be sure to check-in the old and new directories when you are done.
cleartool co .
cleartool co newdirectory
cleartool mv anelement newdirectory
cleartool ci .
cleartool ci newdirectory
Renaming an element is also accomplished using the cleartool mv command except the old directory and the new directory are the same.
cleartool co .
cleartool mv anelement anewname
cleartool ci .
In subsequent versions of the directory, the name anelement will not appear, having been replaced by anewname but the name anelement will still appear in prior versions of the directory. Both the names anewname and anelement will still refer to the same element; only the name associated with the element in the directory will have changed.
.
Getting information
More about Views
What View am I in?
At any given time you can tell what view you are in by issuing the following command:
cleartool pwv
pwv means "print working view" in the tradition of the UNIX command pwd for "print working directory"
What is my "config-spec"?
Recall that a configuration specification (config-spec) is the set of rules that tells ClearCase what configuration of elements you want to work with. You can see that set of rules by issuing the following command:
cleartool catcs
How do I change my config-spec?
You can edit your config-spec by issuing the following command:
cleartool edcs
Your favorite editor , as specified by the environment variable WINEDITOR (first choice), VISUAL (second choice), or EDITOR (third choice) will be invoked for the editing operation. If none of these environment variables is set then vi will be invoked for the editing operation on UNIX systems and Notepad will be invoked for the editing operation on Windows systems.
About files/directories
What is checked-out and to whom?
If you want to see who has what checked-out, you can use the cleartool lsco command. This command has a number of possible arguments to use depending on the specific information you want. Here are some common ones:
cleartool lsco
Lists all checkouts of elements in the current directory.
cleartool lsco anelement
List checkout information about the element anelement.
cleartool lsco -recurse
Lists all checkouts of elements in the current directory and below.
cleartool lsco -cview
Lists checkouts of elements in the current directory that are checked-out to the current view.
cleartool lsco -cview -recurse
Lists checkouts of elements in the current directory and below that are checked-out to the current view.
cleartool lsco -me
Lists checkouts of elements in the current directory that the current user has checked-out.
cleartool lsco -user fred
Lists checkouts of elements in the current directory that the user with login id "fred" has checked-out.
Please refer to the ClearCase Reference Manual for more detailed information about the cleartool lsco command.
What is the change history of this file/directory?
If you want to see the change history associated with a particular element, you can use the cleartool lsh command.
cleartool lsh anelement
Where anelement is the name of an element under ClearCase control
What versions of what files/directories am I looking at?
To see exactly what versions of elements are being projected to you by your view and why, you can use the cleartool ls command.
cleartool ls
What are the differences between this version of a file/directory and a different version?
To view the differences between the versions of an element visible in your view and another version of the element you can use the cleartool diff command.
cleartool diff -g -pred anelement
Graphically presents the differences between the version of anelement selected by your view and it's immediate predecessor version.
cleartool diff -g anelement anelement@@/main/5
Graphically presents the differences between the version of anelement selected by your view and version 5 on the main branch of anelement.
You can also use this command without the -g option to present the difference information to you textually rather than graphically.
See the cleartool diff entry in the ClearCase Reference Manual for more detailed information on these commands.
What does the version tree look like for this file/directory?
To view a graphical representation of the version tree associated with an element you can use the xlsvtree command.
cleartool lsvtree -g anelement
You can view a textual representation of the version tree associated with an element with the cleartool lsvtree command.
cleartool lsvtree anelement
I want more information about this element?
You can get more detailed information about a particular element with the cleartool describe command.
cleartool describe anelement
Lists information about anelement such as the version selected by your view, who created it and when, the comment associated with the version, the element type and the predecessor version.
Resources
Learn
• 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.
• To get your team up to speed on IBM Rational product technology as quickly as possible, IBM Global Services offers a variety of classroom training. Attend a public session, or arrange to have the course delivered at your site. If you prefer a self-paced, online training experience, there are a variety of web-based training modules available.
• Read about the latest release of the IBM Rational Software Delivery Platform in the developerWorks article: Accelerating global software delivery.
• Learn more about how to benefit from IBM Rational products and technologies in The Rational Edge e-zine.
• Browse the technology bookstore for books on these and other technical topics.
• Learn about upcoming events; including webcasts, seminars, trade shows, user group meetings, and the IBM Rational Software Development User Conference.
• Whitepapers, analyst reports, and datasheets for IBM Rational ClearCase are available here.
• IBM Rational software has helped thousands of companies worldwide achieve success in their software development efforts. Read about some of them here.
Get products and technologies
• Download this information as a printable brochure in pdf format.
• 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.
• Product manuals, installation guides, and other documentation are available in the IBM Rational Online Documentation Center.
Discuss
• 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.
Showing posts with label clearcase articles. Show all posts
Showing posts with label clearcase articles. Show all posts
Using Perl with Rational ClearCase Automation Library (CAL)
Software Engineering Specialist
Rational Services Organization
As a consultant for Rational, I spend a great
deal of time working directly with Rational
customers. Typically, I work together with
Rational ClearCase® users to develop a
customized solution to whatever unique
challenge they are facing. Often in these
encounters, I have found the sometimes
overlooked ClearCase Automation Library (CAL)
to be an especially handy tool for accessing
and manipulating ClearCase data
programmatically in a wide variety of
situations.
Starting with ClearCase 4.0, both CAL and the
CAL documentation are automatically installed
with Rational ClearCase on Windows platforms.
CAL provides a set of COM (Component Object
Model) interfaces that are intended both as an
integration platform and also as an API (Application Program Interface) that
you can use to extend or customize Rational ClearCase. You can also use CAL
to write scripts, stand-alone programs, or macros embedded in other
applications. Because CAL is a COM-compliant library, you can use it from
within any tool that can interface with COM, including Visual Basic, Visual C++,
and Perl on Windows. Since COM is primarily a Windows-only technology, CAL
is not available on UNIX platforms.
In this article, I'm going to talk about why you might want to use CAL, and
some tools and resources that are useful for working with CAL in the Perl
programming language. I'll also walk through a fairly simple Perl application
that uses CAL as well as the Rational ClearQuest® API to generate a report
combining ClearCase and ClearQuest data. An in-depth discussion of the
Rational ClearQuest API is beyond the scope of this article, but it will be
addressed in an upcoming edition of The Rational Edge.
A Very Quick Tech Review
In general, the concepts I'll discuss here are fairly straightforward and should
be readily understandable by a technical audience. However, some basic
familiarity -- or expertise -- in the following areas will help you get the most
from this discussion:
l Software configuration management concepts in general and
Rational ClearCase in particular. A quick review: Rational ClearCase
is the market-leading tool for software asset management. Rational
ClearQuest is a highly flexible defect and change tracking tool. Together,
they enable Unified Change Management (UCM), Rational's out-of-the
box process for managing change at the activity level.
l The Perl Programming Language. Perl is a remarkably popular
programming language. Relatively easy to learn and often available for
free, it has been described as the duct tape of not only the Internet, but
also the entire computing world. If you're looking to learn Perl or just
brush up on it, I recommend Learning Perl (the book with the llama on
the cover) and for a more advanced reference Programming Perl1 (the
book with the camel on the cover), both from O'Reilly & Associates. The
latter title is included in the Perl CD Bookshelf -- see Useful Tools below.
l COM or Component Object Model. Developed by Microsoft, COM is a
standard that defines a mechanism for software components to interact
with each other. COM is an object-oriented technology, and its main
building blocks are objects, interfaces, methods, and properties. There
are numerous excellent resources and books on COM2, and even the
more basic ones should give you enough information to start using CAL.
Why CAL?
You may already be familiar with another common method of accessing
Rational ClearCase data from outside the Rational ClearCase user interface. The
cleartool utility is a command-line interface that you can use to create, modify,
and manage the information in Rational ClearCase VOBs (Versioned Object
Bases) and views. The flexibility and ease of use of cleartool makes it an ideal
solution for a wide range of problems. And in one sense, cleartool has always
offered a kind of API to ClearCase, for both Windows and UNIX platforms.
However, there are situations in which CAL offers a superior alternative to
cleartool -- specifically when speed and performance are factors.
Certain languages are not well suited to invoking command-line tools and
parsing the results; Visual Basic is a good example. Parsing results can be
somewhat difficult in the C programming language as well. Perl, on the other
hand, makes it easy to start command-line utilities and parse the results. But
even when using Perl, you may want greater speed. Because CAL does not
create a new process for each invocation, it can be considerably faster than a
solution that uses cleartool's command-line interface. When a program invokes
cleartool, the operating system must create a new process, and there is a
significant amount of overhead associated with starting that new process --
allocating memory for it, creating a new entry in the process table, and so on.
I recently did some very basic performance measurements by timing a task
that I completed with cleartool and then timing the same task using a CAL
implementation instead. For this specific operation, CAL was about 30 percent
faster. While these results are empirical, and fairly rough, they show that CAL
can offer a significant advantage when speed is important.
Useful Tools
Of course, CAL itself and the CAL documentation are essential for developing
Perl scripts that access ClearCase data (without using cleartool). If you've
installed Rational ClearCase, then you already have CAL and the documentation
on your system.
Documentation for CAL includes conceptual material, diagrams, several
examples, and reference pages for each interface in CAL. There are several
other tools -- some essential, some merely handy -- that I find valuable in
Perl/CAL development.
As I mentioned earlier, CAL is a standard COM interface, which means that it
will work with any tool that supports COM. This includes some, but not all,
versions of Perl. The version of Perl that comes with ClearCase, ccperl, does not
support COM. If you want to use CAL with Perl, you will need to use another
Perl distribution. I've found ActivePerl from ActiveState3 to be a great tool. It is
a nice, robust implementation, and best of all it is free. Plus, the ActivePerl
distribution includes a Perl package manager, which automatically finds and
installs Perl packages. This is helpful for COM developers because you have to
install a COM package in order to use COM in Perl.
The inexpensive Perl Development Kit, also available from ActiveState, is
another extremely useful tool. If you plan to do Perl development in any
serious sense, it is probably one of the best investments you can make. The
two components I have used most are the Perl debugger -- which allows you to
step through code, set breakpoints and watch variables -- and PerlApp, which
allows you to convert a Perl application into a completely self-contained
Windows program that can be run on any system, even if the system does not
have a Perl interpreter.
The second edition of the Perl CD Bookshelf from O'Reilly includes searchable
online copies of the following Perl references: Perl in a Nutshell, Programming
Perl, 3rd Ed., Perl Cookbook, Advanced Perl Programming, and Perl for System
Administration. This resource includes source code that you can cut-and-paste,
which is an exceptionally common (and convenient) practice in Perl
Programming. Legend has it that only one Perl program was ever written -- all
the rest were derived from it. I take a copy of this CD everywhere I go,
because it is just too useful to be without.
Some other tools and resources that are useful (but not required) in this
context include:
l Rational SoDA. Rational SoDA is an automated report generator that
has the ability to pull together static data from a variety of Rational
tools. For example, it can reach into Rational ClearCase and Rational
ClearQuest repositories, and build a report based on a template that you
define. However, Rational SoDA cannot perform interactive queries and
then take action based on the results -- something a Perl script can do
with ease.
l Rational ClearQuest API and Documentation. Like Rational
ClearCase, Rational ClearQuest also offers a COM library that you can
use to access its data. The Rational ClearQuest API is used by external
programs to view or modify the data that Rational ClearQuest stores in
the user database and schema repository. The sample Perl application
we'll look at in this article, changeset_report.pl, uses the Rational
ClearQuest API to query the Rational ClearQuest database.
l Visual Basic. I use Visual Basic to quickly develop prototypes and test
programs. Visual Basic has extensive COM support and a built-in IDE
(Integrated Development Environment), which makes it handy for
troubleshooting any problems you might have with COM interfaces,
including CAL. Visual Basic's object browser is also helpful for examining
COM interfaces in an easy-to-understand format.
A Sample Project
Recently, while working with a customer, I came across a situation ideally
suited to a CAL-based solution written in Perl. To understand this customer's
particular needs, a little background will be helpful. Rational ClearCase and
Rational ClearQuest store data in different data domains. Each tool provides
extensive reporting capabilities within its respective data domain. Rational
ClearCase uses cleartool subcommands such as cleartool find and cleartool
describe for locating and reporting on ClearCase-controlled data, and more
recent versions of ClearCase include ClearCase Report Builder, which uses a
library of report programs to support dozens of standard report options.
Rational ClearQuest uses Crystal Reports. There is, of course, integration
between the two tools that allows them to share data. For example, if you
enable UCM with Rational ClearQuest and Rational ClearCase, a link is made
between change requests and activities, so that when you access an activity in
Rational ClearCase, Rational ClearQuest gives you information about the
change request or defect associated with that activity.
Rational ClearQuest maintains information about the process, the state of the
activity, and so on; Rational ClearCase maintains the activity objects -- the
actual change set information. In UCM, that information always stays in the
Rational ClearCase database to avoid replicating information unnecessarily4.
Now, let's say you were doing a code review, and you wanted a report that
showed all the open and active defects in Rational ClearQuest, including the
state of the defect, the owner, etc. -- and you also wanted to include the
change set to show what code needed to be reviewed.
In fact, this is exactly what the customer wanted to do. The solution, as you
have probably guessed, was to write a simple Perl script that uses CAL and the
Rational ClearQuest API to create a report with just the change set information
that they needed.
Figure 1: The Perl Application changeset_report.pl Uses CAL and the Rational ClearQuest
API
The Perl application, changeset_report.pl, queries the Rational ClearQuest
database via the Rational ClearQuest API to obtain a list of ClearQuest records.
For each record, the program gets the Rational ClearCase UCM activity, and
uses CAL to extract the change set information for that activity. The program
then prints a report based on the data it finds.
Now let's look at the commented source code for changeset_report.pl. As we
discuss the highlights and most important CAL-related aspects, you'll find it
helpful to refer to the full code to better see how the pieces fit together.
Because the application was actually developed for use in the real world, there
are some added features that make it easier to use, but that you would not
necessarily find in an example application focused solely on using CAL. For
example, although all of the changeset_report.pl options and parameters can be
set via the command line switches, there is also a Tk5-based graphical user
interface (GUI) that prompts the user for any missing information (see Figure
2).
Figure 2: The Tk-Based Front End of changeset_report.pl
The sample program also includes an option for sending the output to an Excel
spreadsheet instead of printing it out. Finally, although use of the ClearQuest
API is an integral part of this sample application, we'll focus primarily on the
sections related to CAL. In particular, the steps used to access Rational
ClearQuest -- including creating a ClearQuest session, building the query, and
getting results -- are not explained in detail here.
A Walk Through the Code
The first important line to note in the script is the first non-comment line:
use Win32::OLE;
Essentially, this line includes the Win32::OLE package so that it can be used in
our script.
After the program has processed the command-line switches (or the input from
the GUI), and builds a list of ClearQuest records, it enters a loop that is
repeated for every ClearQuest record returned. In that loop, which appears
considerably later in the script, CAL is instantiated for any ClearQuest record
that contains a ucm_vob_object field. In UCM, the VOB object identifies the
change set associated with a particular activity. If the ClearQuest results
include an identifier for this object, then the script uses Win32::OLE to create a
new ClearCase Application object, as you can see below.
#----------------------------------------------------------------
# If the CC activity ID is not null, then we need to use CAL
# to extract the changeset info from the CC activity object
#----------------------------------------------------------------
print "Instantiating CAL\n" if $DEBUG;
my ($CCApp) = Win32::OLE->new("ClearCase.Application") or
die "Can't create ClearCase application object via
call to Win32::OLE->new(): $!";
The two entry points for interacting with CAL are the Application object and the
ClearTool object. Most applications -- including this sample application -- use
the Application object, as it exposes most of the CAL API. The ClearTool object
contains a single method, CmdExec, which can be used to execute a cleartool
subcommand string. This ensures that any capabilities in cleartool not covered
by the Application object are accessible programmatically. The code above
instantiates a ClearCase Application object named $CCapp. The my operator
simply limits the scope of the $CCApp variable. If the Application object cannot
be created, then the script terminates or "dies" with an appropriate error
message. The "print…$DEBUG" line in the code above and throughout the script
serves as a rudimentary -- but very common -- debugging mechanism. If you
don't want to use the Perl debugger, you can enable this verbose output by
simply un-commenting the $DEBUG = 1 line located near the start of the script.
Once we have an Application object, we use the Activity()method to obtain an
activity object from the value of the ucm_vob_object field that we obtained from
Rational ClearQuest, as shown below.
#----------------------------------------------------------------
# Get an activity object from CAL
#----------------------------------------------------------------
$myactivity = $CCApp->Activity($activity_id);
The result is an activity object, which I assign to $myactivity. To resolve the
names of objects in an activity's change set, Rational ClearCase requires a view
context. You can have ClearCase identify the best view heuristically, using the
NameResolverView property of the activity. This view can, in turn, be used to
resolve names of objects in the activity change set:
$view = $myactivity->NameResolverView;
To get the actual change set, we call the ChangeSet() method of the activity
object, which returns a Collection object containing change set entries or
CCVersions:
#----------------------------------------------------------------
# Get the activity's change set, which is a CCVersions collection
# Use the activity's "nameresolver view" for name resolution.
#----------------------------------------------------------------
$ChangeSet = $myactivity->ChangeSet($view, "False");
$CS_Entries = $ChangeSet->Count;
At this point, the script enumerates the change set entries and accesses the
path name of each changed source file via the ExtendedPath property.
#----------------------------------------------------------------
# Loop through the CCVersions collection, collecting the names of
# the versions for printing.
#----------------------------------------------------------------
print "Getting ChangeSet info\n" if $DEBUG;
$CS_Index = 1;
while ($CS_Index <= $CS_Entries) {
.
.
.
$Version = $ChangeSet->Item($CS_Index);
$VersionPN = $Version->ExtendedPath;
.
.
.
$CS_Index++;
}
After iterating over each element of the change set collection, the script prints
the results (or sends them to Microsoft Excel), and then repeats the process on
the next ClearQuest record until there are no more. Sample output from
changeset_report.pl is shown in Figures 3A and 3B.
Figure 3A: Sample Standard Output from changeset_report.pl
Figure 3B: Sample Microsoft Excel Output from changeset_report.pl
What's Next?
The changeset_report.pl script is not exceptionally complicated. In fact, it uses
only a small subset of the capabilities offered by CAL. The CAL documentation
includes a comprehensive list of all the CAL interfaces, as well as additional
sample applications (including a couple more written in Perl). So, while
changeset_report.pl illustrates only a fraction of what you can do with CAL, it
does show how useful and practical CAL can be with a minimum of effort. With
this small Perl program, we can see how easy it is to use CAL and the Rational
ClearQuest API to access Rational ClearCase and ClearQuest data
programmatically.
In fact, there are a myriad of different uses for CAL; and you've probably
already thought of a few yourself. One possible use that I have started to play
with is a kind of "release manager" application -- a utility that would present
the user with a choice of baselines from which to construct a particular
configuration and generate release notes based on the selected baseline.
Although I have not finished it yet, working on it has reminded me how
valuable CAL is, and how many possible applications it has. Once you start
using it, I'm sure you'll find even more.
Rational Services Organization
As a consultant for Rational, I spend a great
deal of time working directly with Rational
customers. Typically, I work together with
Rational ClearCase® users to develop a
customized solution to whatever unique
challenge they are facing. Often in these
encounters, I have found the sometimes
overlooked ClearCase Automation Library (CAL)
to be an especially handy tool for accessing
and manipulating ClearCase data
programmatically in a wide variety of
situations.
Starting with ClearCase 4.0, both CAL and the
CAL documentation are automatically installed
with Rational ClearCase on Windows platforms.
CAL provides a set of COM (Component Object
Model) interfaces that are intended both as an
integration platform and also as an API (Application Program Interface) that
you can use to extend or customize Rational ClearCase. You can also use CAL
to write scripts, stand-alone programs, or macros embedded in other
applications. Because CAL is a COM-compliant library, you can use it from
within any tool that can interface with COM, including Visual Basic, Visual C++,
and Perl on Windows. Since COM is primarily a Windows-only technology, CAL
is not available on UNIX platforms.
In this article, I'm going to talk about why you might want to use CAL, and
some tools and resources that are useful for working with CAL in the Perl
programming language. I'll also walk through a fairly simple Perl application
that uses CAL as well as the Rational ClearQuest® API to generate a report
combining ClearCase and ClearQuest data. An in-depth discussion of the
Rational ClearQuest API is beyond the scope of this article, but it will be
addressed in an upcoming edition of The Rational Edge.
A Very Quick Tech Review
In general, the concepts I'll discuss here are fairly straightforward and should
be readily understandable by a technical audience. However, some basic
familiarity -- or expertise -- in the following areas will help you get the most
from this discussion:
l Software configuration management concepts in general and
Rational ClearCase in particular. A quick review: Rational ClearCase
is the market-leading tool for software asset management. Rational
ClearQuest is a highly flexible defect and change tracking tool. Together,
they enable Unified Change Management (UCM), Rational's out-of-the
box process for managing change at the activity level.
l The Perl Programming Language. Perl is a remarkably popular
programming language. Relatively easy to learn and often available for
free, it has been described as the duct tape of not only the Internet, but
also the entire computing world. If you're looking to learn Perl or just
brush up on it, I recommend Learning Perl (the book with the llama on
the cover) and for a more advanced reference Programming Perl1 (the
book with the camel on the cover), both from O'Reilly & Associates. The
latter title is included in the Perl CD Bookshelf -- see Useful Tools below.
l COM or Component Object Model. Developed by Microsoft, COM is a
standard that defines a mechanism for software components to interact
with each other. COM is an object-oriented technology, and its main
building blocks are objects, interfaces, methods, and properties. There
are numerous excellent resources and books on COM2, and even the
more basic ones should give you enough information to start using CAL.
Why CAL?
You may already be familiar with another common method of accessing
Rational ClearCase data from outside the Rational ClearCase user interface. The
cleartool utility is a command-line interface that you can use to create, modify,
and manage the information in Rational ClearCase VOBs (Versioned Object
Bases) and views. The flexibility and ease of use of cleartool makes it an ideal
solution for a wide range of problems. And in one sense, cleartool has always
offered a kind of API to ClearCase, for both Windows and UNIX platforms.
However, there are situations in which CAL offers a superior alternative to
cleartool -- specifically when speed and performance are factors.
Certain languages are not well suited to invoking command-line tools and
parsing the results; Visual Basic is a good example. Parsing results can be
somewhat difficult in the C programming language as well. Perl, on the other
hand, makes it easy to start command-line utilities and parse the results. But
even when using Perl, you may want greater speed. Because CAL does not
create a new process for each invocation, it can be considerably faster than a
solution that uses cleartool's command-line interface. When a program invokes
cleartool, the operating system must create a new process, and there is a
significant amount of overhead associated with starting that new process --
allocating memory for it, creating a new entry in the process table, and so on.
I recently did some very basic performance measurements by timing a task
that I completed with cleartool and then timing the same task using a CAL
implementation instead. For this specific operation, CAL was about 30 percent
faster. While these results are empirical, and fairly rough, they show that CAL
can offer a significant advantage when speed is important.
Useful Tools
Of course, CAL itself and the CAL documentation are essential for developing
Perl scripts that access ClearCase data (without using cleartool). If you've
installed Rational ClearCase, then you already have CAL and the documentation
on your system.
Documentation for CAL includes conceptual material, diagrams, several
examples, and reference pages for each interface in CAL. There are several
other tools -- some essential, some merely handy -- that I find valuable in
Perl/CAL development.
As I mentioned earlier, CAL is a standard COM interface, which means that it
will work with any tool that supports COM. This includes some, but not all,
versions of Perl. The version of Perl that comes with ClearCase, ccperl, does not
support COM. If you want to use CAL with Perl, you will need to use another
Perl distribution. I've found ActivePerl from ActiveState3 to be a great tool. It is
a nice, robust implementation, and best of all it is free. Plus, the ActivePerl
distribution includes a Perl package manager, which automatically finds and
installs Perl packages. This is helpful for COM developers because you have to
install a COM package in order to use COM in Perl.
The inexpensive Perl Development Kit, also available from ActiveState, is
another extremely useful tool. If you plan to do Perl development in any
serious sense, it is probably one of the best investments you can make. The
two components I have used most are the Perl debugger -- which allows you to
step through code, set breakpoints and watch variables -- and PerlApp, which
allows you to convert a Perl application into a completely self-contained
Windows program that can be run on any system, even if the system does not
have a Perl interpreter.
The second edition of the Perl CD Bookshelf from O'Reilly includes searchable
online copies of the following Perl references: Perl in a Nutshell, Programming
Perl, 3rd Ed., Perl Cookbook, Advanced Perl Programming, and Perl for System
Administration. This resource includes source code that you can cut-and-paste,
which is an exceptionally common (and convenient) practice in Perl
Programming. Legend has it that only one Perl program was ever written -- all
the rest were derived from it. I take a copy of this CD everywhere I go,
because it is just too useful to be without.
Some other tools and resources that are useful (but not required) in this
context include:
l Rational SoDA. Rational SoDA is an automated report generator that
has the ability to pull together static data from a variety of Rational
tools. For example, it can reach into Rational ClearCase and Rational
ClearQuest repositories, and build a report based on a template that you
define. However, Rational SoDA cannot perform interactive queries and
then take action based on the results -- something a Perl script can do
with ease.
l Rational ClearQuest API and Documentation. Like Rational
ClearCase, Rational ClearQuest also offers a COM library that you can
use to access its data. The Rational ClearQuest API is used by external
programs to view or modify the data that Rational ClearQuest stores in
the user database and schema repository. The sample Perl application
we'll look at in this article, changeset_report.pl, uses the Rational
ClearQuest API to query the Rational ClearQuest database.
l Visual Basic. I use Visual Basic to quickly develop prototypes and test
programs. Visual Basic has extensive COM support and a built-in IDE
(Integrated Development Environment), which makes it handy for
troubleshooting any problems you might have with COM interfaces,
including CAL. Visual Basic's object browser is also helpful for examining
COM interfaces in an easy-to-understand format.
A Sample Project
Recently, while working with a customer, I came across a situation ideally
suited to a CAL-based solution written in Perl. To understand this customer's
particular needs, a little background will be helpful. Rational ClearCase and
Rational ClearQuest store data in different data domains. Each tool provides
extensive reporting capabilities within its respective data domain. Rational
ClearCase uses cleartool subcommands such as cleartool find and cleartool
describe for locating and reporting on ClearCase-controlled data, and more
recent versions of ClearCase include ClearCase Report Builder, which uses a
library of report programs to support dozens of standard report options.
Rational ClearQuest uses Crystal Reports. There is, of course, integration
between the two tools that allows them to share data. For example, if you
enable UCM with Rational ClearQuest and Rational ClearCase, a link is made
between change requests and activities, so that when you access an activity in
Rational ClearCase, Rational ClearQuest gives you information about the
change request or defect associated with that activity.
Rational ClearQuest maintains information about the process, the state of the
activity, and so on; Rational ClearCase maintains the activity objects -- the
actual change set information. In UCM, that information always stays in the
Rational ClearCase database to avoid replicating information unnecessarily4.
Now, let's say you were doing a code review, and you wanted a report that
showed all the open and active defects in Rational ClearQuest, including the
state of the defect, the owner, etc. -- and you also wanted to include the
change set to show what code needed to be reviewed.
In fact, this is exactly what the customer wanted to do. The solution, as you
have probably guessed, was to write a simple Perl script that uses CAL and the
Rational ClearQuest API to create a report with just the change set information
that they needed.
Figure 1: The Perl Application changeset_report.pl Uses CAL and the Rational ClearQuest
API
The Perl application, changeset_report.pl, queries the Rational ClearQuest
database via the Rational ClearQuest API to obtain a list of ClearQuest records.
For each record, the program gets the Rational ClearCase UCM activity, and
uses CAL to extract the change set information for that activity. The program
then prints a report based on the data it finds.
Now let's look at the commented source code for changeset_report.pl. As we
discuss the highlights and most important CAL-related aspects, you'll find it
helpful to refer to the full code to better see how the pieces fit together.
Because the application was actually developed for use in the real world, there
are some added features that make it easier to use, but that you would not
necessarily find in an example application focused solely on using CAL. For
example, although all of the changeset_report.pl options and parameters can be
set via the command line switches, there is also a Tk5-based graphical user
interface (GUI) that prompts the user for any missing information (see Figure
2).
Figure 2: The Tk-Based Front End of changeset_report.pl
The sample program also includes an option for sending the output to an Excel
spreadsheet instead of printing it out. Finally, although use of the ClearQuest
API is an integral part of this sample application, we'll focus primarily on the
sections related to CAL. In particular, the steps used to access Rational
ClearQuest -- including creating a ClearQuest session, building the query, and
getting results -- are not explained in detail here.
A Walk Through the Code
The first important line to note in the script is the first non-comment line:
use Win32::OLE;
Essentially, this line includes the Win32::OLE package so that it can be used in
our script.
After the program has processed the command-line switches (or the input from
the GUI), and builds a list of ClearQuest records, it enters a loop that is
repeated for every ClearQuest record returned. In that loop, which appears
considerably later in the script, CAL is instantiated for any ClearQuest record
that contains a ucm_vob_object field. In UCM, the VOB object identifies the
change set associated with a particular activity. If the ClearQuest results
include an identifier for this object, then the script uses Win32::OLE to create a
new ClearCase Application object, as you can see below.
#----------------------------------------------------------------
# If the CC activity ID is not null, then we need to use CAL
# to extract the changeset info from the CC activity object
#----------------------------------------------------------------
print "Instantiating CAL\n" if $DEBUG;
my ($CCApp) = Win32::OLE->new("ClearCase.Application") or
die "Can't create ClearCase application object via
call to Win32::OLE->new(): $!";
The two entry points for interacting with CAL are the Application object and the
ClearTool object. Most applications -- including this sample application -- use
the Application object, as it exposes most of the CAL API. The ClearTool object
contains a single method, CmdExec, which can be used to execute a cleartool
subcommand string. This ensures that any capabilities in cleartool not covered
by the Application object are accessible programmatically. The code above
instantiates a ClearCase Application object named $CCapp. The my operator
simply limits the scope of the $CCApp variable. If the Application object cannot
be created, then the script terminates or "dies" with an appropriate error
message. The "print…$DEBUG" line in the code above and throughout the script
serves as a rudimentary -- but very common -- debugging mechanism. If you
don't want to use the Perl debugger, you can enable this verbose output by
simply un-commenting the $DEBUG = 1 line located near the start of the script.
Once we have an Application object, we use the Activity()method to obtain an
activity object from the value of the ucm_vob_object field that we obtained from
Rational ClearQuest, as shown below.
#----------------------------------------------------------------
# Get an activity object from CAL
#----------------------------------------------------------------
$myactivity = $CCApp->Activity($activity_id);
The result is an activity object, which I assign to $myactivity. To resolve the
names of objects in an activity's change set, Rational ClearCase requires a view
context. You can have ClearCase identify the best view heuristically, using the
NameResolverView property of the activity. This view can, in turn, be used to
resolve names of objects in the activity change set:
$view = $myactivity->NameResolverView;
To get the actual change set, we call the ChangeSet() method of the activity
object, which returns a Collection object containing change set entries or
CCVersions:
#----------------------------------------------------------------
# Get the activity's change set, which is a CCVersions collection
# Use the activity's "nameresolver view" for name resolution.
#----------------------------------------------------------------
$ChangeSet = $myactivity->ChangeSet($view, "False");
$CS_Entries = $ChangeSet->Count;
At this point, the script enumerates the change set entries and accesses the
path name of each changed source file via the ExtendedPath property.
#----------------------------------------------------------------
# Loop through the CCVersions collection, collecting the names of
# the versions for printing.
#----------------------------------------------------------------
print "Getting ChangeSet info\n" if $DEBUG;
$CS_Index = 1;
while ($CS_Index <= $CS_Entries) {
.
.
.
$Version = $ChangeSet->Item($CS_Index);
$VersionPN = $Version->ExtendedPath;
.
.
.
$CS_Index++;
}
After iterating over each element of the change set collection, the script prints
the results (or sends them to Microsoft Excel), and then repeats the process on
the next ClearQuest record until there are no more. Sample output from
changeset_report.pl is shown in Figures 3A and 3B.
Figure 3A: Sample Standard Output from changeset_report.pl
Figure 3B: Sample Microsoft Excel Output from changeset_report.pl
What's Next?
The changeset_report.pl script is not exceptionally complicated. In fact, it uses
only a small subset of the capabilities offered by CAL. The CAL documentation
includes a comprehensive list of all the CAL interfaces, as well as additional
sample applications (including a couple more written in Perl). So, while
changeset_report.pl illustrates only a fraction of what you can do with CAL, it
does show how useful and practical CAL can be with a minimum of effort. With
this small Perl program, we can see how easy it is to use CAL and the Rational
ClearQuest API to access Rational ClearCase and ClearQuest data
programmatically.
In fact, there are a myriad of different uses for CAL; and you've probably
already thought of a few yourself. One possible use that I have started to play
with is a kind of "release manager" application -- a utility that would present
the user with a choice of baselines from which to construct a particular
configuration and generate release notes based on the selected baseline.
Although I have not finished it yet, working on it has reminded me how
valuable CAL is, and how many possible applications it has. Once you start
using it, I'm sure you'll find even more.
Common ClearCase Practices
Best Practices, Traps, and Pitfalls
Introduction
This page attempts to catalog common practices with the ClearCase software configuration management tool. At present, no attempt is made to distinguish which practices are "good"and which ones aren't. At a later date, I hope to be able to sort the common usage patterns listed here into "best practices"and "traps and pitfalls."
I hope to determine this by having people from various development shops answer the following questions for each practice that they actually use:
* Do they consider it a "best-practice"? Why or why not? (what is the rationale)
* What is the underlying problem the practice solves for them?
* What are the benefits they see resulting from its use?
* What are the drawbacks (tradeoffs) they see? How are they handled?
* What circumstances make this a "best-practice" for them that might make the practice inappropriate under different project conditions?
* What were the motivating factors that made this alternative more attractive than others that might have been considered?
* What related practices do they use that depend upon (or are depended upon by) this one?
Currently, the practices are partitioned into the following areas (with some overlap):
o Branches
o Labels
o Configuration Records
o Attributes
o Hyperlinks
o Triggers
o Locks
o Multi-Site
o Tool-Supported Roles/States
o VOB Management
o View Management
o Config-Spec Management & Version Selection
o Version Management
o Integration with Tracking System
o Document Management
o Release Management
o Access Control/Restrictions
o Change Control Boards
Branches
* Branch Naming Conventions
* Task Branches
* Integration Branches
* Release Branches
Early Branching
Early Branching is when codelines for new development or integration are created right away, as soon as any work on the corresponding project or release begins. This is often used when the mainline is a "Stable Receiving Line" reserved only for merges of baselines. New codelines are spawned off the mainline as soon as the corresponding work begins.
For example, if work on release 1.0 has completed and work on 1.1 is taking place, and at the same time, work on release 2.0 is about to start, then a new codeline is branched off mainline for work on release 2.0 at that point (and if it isn't already, work on release 1.1 and other version 1 maintenance releases) goes on its own branch.
Thus Early Branching merges into mainline with the old baseline, and then branches out from mainline for the new development/release.
Deferred Branching
In contrast to "Early Branching", Deferred Branching (also called Lazy Branching) is when branch creation for new development/integration codelines is put off until the last minute. This is often used when the mainline is a "Latest and Greatest Development Line" (or "LAG Line"). The latest and greatest development work takes place on the mainline, or the main development line (which might not be /main), and codelines are branched off only when the corresponding work is no longer the latest and greatest.
For example, when working on release 1.0, development happens on the mainline. Work on 1.1 and 1.2 (and 1.x) also happens on the mainline until work on the next release (2.0) starts to take place in parallel. At that point, development for release 2.0 takes over the mainline, and then a separate branch is created for maintenance work on release 1.x.
Thus, instead of branching for a new release-line as soon as work begins on the release, we wait to branch it off mainline, until it goes into maintenance mode or until development on a subsequent release begins in parallel from existing work. At which time its out with the old (it gets a new codeline branched out from main) and in with the new (the new development work comes in on the mainline).
The reasoning here is that by branching later rather than earlier, there is a single codeline for a longer period of time and changes simply get merged into the single codeline instead of having to get merged into two parallel codelines. Once the second codeline is split off from the first (regardless of early or late creation), then changes made in the newly branched codeline often need to be propagated back to the parent codeline somehow (either my merging the changes themselves, or by merging the codeline to its parent to "synch-up"). This is a trade-off of safety in favor of liveness (productivity): by waiting longer before splitting off a new codeline, the amount of propagation and synch-ing effort is reduced, at the risk of having less separation/isolation of change.
Directory Branching
Some shops avoid branching directories in ClearCase because when directories are created on a branch, or their contents are altered on a branch (a file is added or removed to its list of elements), they sometimes run into problems with visibility of elements, often resulting in the same element being created twice on different branches.
Other shops use branches for directories in the same way they would for any other elements. And if they have a reasonably organized and disciplined and consistent use of branching, and are sure to integrate early and often, they tend not to suffer too much from the aforementioned problems.
Branch Naming Conventions
Many groups use specific naming conventions for the various kinds of branches that are created. There will typically be some portion of the name that indicates the type of branch (release-line, component-line, integration-line, fix/feature). If the branch corresponds to a major or minor release, then the release number is usually included. If it corresponds to a record in a tracking database, the database-ID of the record is often part of the branch name as well. Some may also employ the primary developer's username as part of the branch-name.
Branch Type Prefix
Use of a prefix to indicate the type/purpose of a branch (e.g., "rel", "int", "fix", "feat", "dev", "tst", "comp", "prod", "proj", etc.)
Release ID in Branch Name
Use of the major and/or minor release version in a branch name (e.g., "rel1", "rel1.2", "rel2.X").
Request ID in Branch Name
Use of change requests tracking systems corresponding request ID as all or part of the branch name (e.g., "cr123", "bug243", "feat331").
User ID in Branch Name
Use of sole or primary developer's username as all or part of the branch name (e.g., "calvin", "hobbes_bug243", "suzy_feat331").
Component ID in Branch Name
Use of a component-name or subsystem-name as all or part of the branch name (e.g., "GUI_rel2.6", "MMI", "ACG-1234").
Task purpose in Branch Name
Use of an indentifier corresponding to the purpose of the task as all or part of the branch name (e.g., "flush_on_write", "fix1234_confirm-exit").
Task Branches
A Task Branch is a branch that is used only for development of a single task. When the task is completed and the changes have been tested in isolation, then the change-task branch is merged into the integration branch (usually its parent). After the change-task is completed or integrated, its not uncommon for it to be "locked down" (retired) from any future changes.
If all change-tasks must be performed on their own task-branch, this is called the Branch per Task approach. Some groups instead prefer to use a Branch per Major Task creating task branches only for more involved (higher risk or longer-lived) efforts, and performing short and (seemingly) simple tasks "on-line" (directly on the codeline instead of on a separate task-branch).
Fix Branch
A Fix Branch is a task branch created for the purpose of fixing a "bug" in the software.
Branch per Request
This is basically the same thing as "Branch per Task". The main difference is that in this case, branches are only created for formal requests logged in a bugtracking and/or change-request tracking database, and other untracked change-tasks might or might not have their own task-branch.
Feature Branch
One of the more common uses of codelines is to house development work for a specific major or minor release (minor releases are sometimes called "point releases" because they only affect the number after the first "point" in the version name/number). Some groups also use branches to shore up work in major or minor system features, (possibly independent of which release-line they may end up getting merged to).
It's common for a group to use task-branches for enhancements and bugfixes that stem from change-requests and/or bug-reports. Its less common to see this same philosphy applied to initial feature development as well (before an initial baseline is created), or before a codeline goes from pure development mode maintenance (and development) mode.
With feature branches, "feature" tasks are created in the tracking system that correspond to new development features to implement in the next or current release. Some of these features may encompass more than a single discrete development task, but often they will correspond to a single task. (In the case of the former, the feature branch may turn out to be a special kind of subproject line called a "feature line" - feature lines typically are smaller units of functionality than "functional lines").
Private Task-Branches
A "private" task branch is a task-branch that is specifically locked right after creation so that only the assigned individual developer make checkout/checkin any versions on the branch. Sometimes groups simply use "private branches" by explicit convention, but don't actually enforce them using ClearCase locks or triggers.
Shared Task-Branches
A "shared" task branch is a task-branch that is deliberately planned and used for development by two or more people on the same branch and task. This may take place in separate views for each developer, or the developers might use a shared view (to conserve diskspace and network reources) if they can obey conventions to prevent each other from modifying the same sets of files (or at least at the same time).
Task-Migration Branch (a.k.a. Transfer-Branch, Carry-over branch)
A Task-Migration branch (or Carry-over branch) is a change-task branch that is created to propagate a change task from one "mainline" to another "mainline." When a group is using multiple mainlines which are long-lived (sometimes each mainline is a different functional-variant line) then change-tasks made in one mainline often need to be propagated to one or more other mainlines. Since the context in which the original change-task occurred may include things that were specific to its particular variant or configuration, a separate migration branch is created for each mainline to receive the propagated change. This keeps the changes isolated on a separate branch of the new mainline so they can be merged, integrated, and stabilized, before adversely impacting other users of the mainline.
Its not uncommon for task-migration branches to require a partial ordering in their integration to a given mainline. Tasks from the same mainline usually need to be propagated to other mainlines in the same order they were completed in their initial mainline (unless the tasks are completely independent and don't share any common context besides a common baseline).
Codeline-Owner as Integrator
The Codeline-Owner serves as the integrator and is responsible for merges all Task-Branches into the codeline. When development is completed on a task-branch, it has to get merged to the integration codeline. Sometimes this is done at periodic intervals by a special "codeline integrator" who is responsible for performing all integrations into their codeline and maintaining a consistent state.
If done right, it works swell. If done wrong, it can result in a "throw it over the integration wall" scenario where there is very little and/or infrequent communication or cooperation between developers and integrators and working relations between them can become very strained and unproductive. It also makes it harder for each group to appreciate the work and needs of the other and they will frequently resist changes to their own work-habits for the benefit of the other group if they can't perceive any benefit to their own group.
Merge Your Own Code/Change
This is when developers are responsible for merging their own change-tasks back into the codeline. It is usually done as soon as the individual task is completed (including after code-review and unit-test).
If done right and with discipline, this too can work out just great. If done wrong, you can have haphazard changes integrated at irregular times, and consistency and stability of the codeline can be next to impossible to rely upon. Regardless of whether developers or separate integrators merge changes to the codeline, there needs to be a responsible "codeline owner" who takes to heart the duty of ensuring that changes are merged in an organized manner and frequency, and that the codeline is as consistent and stable as possible at all times.
Sync Before Merging (sync before export, pre-merging)
Some shops encourage or require developers to merge the latest state of the codeline into their task branch and view before allowing the change to be integrated to the codeline. This ensures that the merge to the codeline will always be a trivial one (provided its performed very shortly thereafter or else in a controlled order) regardless of whether the merge to the codeline is performed by the developer or an integrator.
The downside of this is decreased separability of the change-task from its initial baseline/context. If any merges were made to files on the task-branch, then the branch now contains (and may depend upon) more changes than just the task plus the baseline it was first branched off from. Backing out such changes can be harder to locate or disentangle unless other measures are taken (like checkpointing the versions on the branch before syncing-up with the codeline). The likelihood of merge problems to be handled by an integrator is often decreased because changes are merged by the developers who made them, and codeline integration is usually trivial. But when a problem does occur, its likely to be more of a hassle to resolve.
The main issue has to do with whether the particular environment makes developers more or less likely to be as familiar with the latest state of the codeline as they are with their own changes. If they are, then the developer is typically best suited to do the merging; otherwise the codeline-owner is usually the better choice (and sometimes you need both :-)
Integration Branches
An Integration Line is a branch that is used primarily, or even exclusively for performing integrations of incoming changes. Some like to make the distinction between an "integration line" versus an "integration "branch" (or "integration-task branch"). They use the term Integration Line to refer to a codeline that is created in advance, ahead of many of the changes that will be integrated. When a change is made on its own task-branch, after the change is debugged and tested, it then gets merged into the already created integration line. So the integration-line lives on after the merged task-branch is completed and remains active to in order to merge many other task-branches as they start and finish during the lifetime of the integration-line.
Integration-Task Branch
In contrast to an Integration Line, an Integration-Task Branch typically doesn't get created until after most of the development changes to integrate have already begun, and often isn't created until most of the development changes are ready to be merged. The "integration-task branch" is then created (and sometimes the codeline is frozen from further development changes until the integration is completed). The integrator then merges in each of the ready-to-be-merged development changes in rapid succession (hopefully in some intelligent order based on change-dependencies). So the lifetime of an integration-task branch usually doesnt span over multiple task-branches; it typically doesnt start until most of the task-branches are well underway and ready for integration.
On-line Development (development allowed on integration line)
Some groups allow developers to checkout/checkin on the integration line. It may be that all development happens on the integration line until an initial baseline is created and/or the codeline goes into "maintenance mode." Or else developers perform minor change-tasks "online" using task-branches only for what they consider "major" changes.
Off-line Development (development only on task-branches)
Some groups forbid development tasks on the integration-line, reserving it only for integration of task-branches (which might be performed by an integrator, or by the developer).
Platform Lines (branching for platform variants)
This is a codeline created to house platform-specific work of the system. It might be for a different operating system, or different hardware, or a different windowing environment. But code specific to the particular operating environment has its own platform-speficic integration line.
The more commonly recommended way to handle this is to use platform specific subdirectories and files. Rather than use a sea of #ifdefs to create conditionally compiled spaghetti code, platform-specific code is split out into separate compilation units in a subdirectory named after that platform (or the platform might be a prefix in the filenames). Then a variable can be used in the Makefile(s) to select the specific platform files and directories.
Platform-directories are usually preferred over platform-branches, but occasionally one runs into cases where platform-branches really do seem to make sense.
Feature-Set Lines (Functional Lines)
If the product being constructed has several different functional variants that need to be built, then either each functional variant is given its own codeline; or else each major function that may be varied is given its own codeline and then the versions from the appropriate mix of functional lines is configured to form the desired functional variant of the product.
Component Lines
Sometimes the system is partitioned up into an explicit list of component or subsystems. And a separate team is often assigned to work on each component. It's not uncommon for each component team to create its own component development barnch as the main integration branch for the component, and then development for the component takes place on the component line, or else on one of its sub-branches and is eventually integrated to the component line.
Baselined versions of each of the various components are usually integrated together to configure a complete system build. Sometimes this is done by having each component line merge its latest state into a system-wide integration line, sometimes it's done simply by integrating in the LATEST versions on each components, and sometimes its done simply by selecting the appropriate baseline label for each component in the config-spec (there is rarely ever any overlap between the sets of files making up a given component).
The difference between a "component line" and a "functional line" is that a functional line is for a variant piece of functionality that is not always part of every released configuration. Whereas a "component" line is reserved for work on a particular subsystem regardless of whether or not it is always released with every configuration.
Subproject Lines
A project line may be thought of as virtually any branch or codeline created for one or more related tasks with a common goal. A release-line (the main development or integration line for a specific release) can be thought as a project line whose goal is to deliver a particular release.
It is extremely common for groups to have a main integration line for their work on a particular release (or project), and for all other work to take place other directly on the release-line, or else on a single branch off the release-line for a single task (a bugfix or enhancement) which then gets merged into the main integration line upon completion.
A Subproject Line is a codeline branched off the main integration line that is used for work which spans more than one development task (and hence more than one "task-branch"). Sometimes two or three people work on interdependent tasks on their own separate branches. Rather than each referring directly to the others branch in their configurations, the create a common subproject integration line for their work, and refer to the subproject line instead of someone else's task branch. When someone needs the latest state of someone else's branch, they ask that person to merge to the subproject branch. When all the interdependent tasks are finished and integrated to the subproject branch, then the subproject branch is ready to be merged back to the main integration line.
So a common indicator of a subproject line is when branches are more than one level deep off the main integration line for the release or project codeline. It helps avoid the scenario of "spaghetti branching" where individual task branches explicitly depend on other task branches in a haphazard fashion, much like the haphazard use of unstructured gotos in a program leads to spaghetti code.
Third-Party Line (Vendor Line, Vendor Branch)
When source-code (or other kinds of files) are supplied by some external third-party vendor or supplier and require local modifications they need to be version controlled. The problem is that this needs to be done in a way that minimizes integration effort when obtaining a new release of files from the supplier while accommodating local changes that had to be made.
The common approach to this problem is to use a Third-Party Line or Vendor Branch. Rather than trying to maintain both the vendor-supplied versions and the locally modified versions on the same codeline, a separate codeline is used to hold only the vendor supplied releases of the files. The first time the files are received, the vendor line is created separate from the local development branch (which one branches off of which isn't a big deal, it can happen either way). Then local changes are made on the local development line. When a new release is received, it is checked-in to the vendor-line, and then merged (integrated) into the local development line.
Staged Integration Lines (Promotion Branches)
Sometimes various "promotion levels" are defined along with the linear progression from one promotion level to the next. The criteria used to decide what constitutes a "promotion level" and when to promote something to the next level may vary widely depending on how the group chooses to define them. These promotion levels may correspond to levels of testing or SQA (e.g., inspected, unit-tested, intg-tested, sys-tested, ...), or to levels of scope/scale (unit, component, subsystem, system, ...), or to levels of authority/responsibility.
One way of using promotion levels is to use a separate integration line per promotion level for each release or each mainline. When a version is merged from one promotion branch to its successor, it has been "promoted" to the new level.
Codeline Promotion (Branch Promotion, Promoted Branches)
Staged Lines is when there is a promotion branch for each promotion level. Codeline Promotion (or Branch Promotion) is when the branches get promoted, rather than the versions. Instead of having a branch-per-level, a single codeline has a "level" or state associated with it that indicates the current promotion level of all versions on that branch-type. (One typically uses an attribute on the brtype to indicate the promotion level, and hyperlinks might even be used to indicate predecessor and successor levels). When the versions on a codeline are deemed stable and ready to proceed to the next level, the level is associated with the branch, and the branch itself is what gets promoted (instead of copymerging all the versions to another branch).
Change Propagation
This deals with propagating changes from other integration branches. If a change is made in one codeline that is needed in another codeline (for example, a bugfix in release 1.0 might happen on the release 1.1 codeline, and the fix also needs to find its way into the release 2.0 codeline), some groups simply wait for some (possibly long) durations before merging those changes from one codeline to the other.
Other groups however will propagate changes early and often, syncing up the changes in one codeline (e.g. the rel-1.1 codeline) with the other codeline (e.g. the rel-2.0 codeline) at regular and frequent intervals (sometimes per-task, other times daily, or weekly).
Release Branches
A Release Branch is a codeline reserved for work towards a particular release or a major release. Usually the release codeline is a kind of integration branch. Sometimes a Release Codeline will have its own separate integration branch, but that is relatively rare.
Major Release Line
A major release codeline is one that would be created for all releases with the same major version number (e.g. 1.0, 1.1, ..., 1.x). So a release 1.x codeline would be used for integration (and/or development) of all features for release 1 and all its subsequent maintenance releases and patches. If early branching was used, the major release line is created right away. Otherwise if lazy (deferred) branching was used, it might not be created until just before or just after the initial major release of that code (in which case most of the development happened on a LAG mainline, and the branch was created for release engineering and integration as well as for subsequent maintenance).
Codeline per Release
This is when a release branch is created for every release (major and minor). More often than not, each release-line is branched off from the mainline (possibly after syncing up the mainline with other release lines first, to "refresh" it with the latest baselines before branching off of it - this helps avoid continually cascading release lines off release lines).
Sometimes a release-line is branched off the major release line for each specific release (instead of from the mainline). In this case the Major release-line may serve as either a "Stable Receiving Line" if Early Branching is used, or a "LAG development line" if Deferred Branching is used.
Codeline per Major Release
Sometimes major-release lines are always created, and branches are only created for a specific release of the major-release in the event they seem absolutely necessary for a bigger/tougher than usual release engineering effort (in which case they are often quickly merged back to the major release-line when finished).
Patch Line
In addition to branching for major or minor releases, sometimes a separate branch is created for a specific patch-effort. The effort might simply be for a single task that results in a released "patch", or it might be more long-lived over several tasks (usually for a limited period of time, like a month or two) and results in a released patch (possibly before or after merging it back to the release-line).
The more common case is where code on the patch-line is released only after everything on the patch-line has been integrated and baselined. However some groups that need to very quickly respond to a set of internal or "in house" users will use the patch-branch (and its corresponding workspace) as a kind of emergency patch-release area to quickly push out incremental fixes to a recent release.
Mainline
A mainline is kind of a "homing line" or "anchor" for all other paths of development branched off from it. If there is only one persistent variant of the code (e.g. no platform-lines nor functional-lines are needed) then only one mainline is usually required. (And in ClearCase this will almost always be "/main".)
Mainlines are typically used primarily for integration, and serve as a stable receiving line; or else they are used as the primary LAG development line. Some groups even use a LAG development mainline that gets periodically merged to an integration mainline.
Mainlines serve as the main-stream from all other major codelines are branched. And every major codeline eventually must merge back to the mainline at periodic intervals and/or before retiring/decommissioning the major codeline. This helps avoid the "continuing cascade problem" where each release-line branches of from its predecessor release, and the predecessor has to propagate its changes to its successor, resulting in a very deep and wide propagation of changes from release-line to release-line with no end in sight.
Using a mainline causes all child codelines to regularly merge back to their common parent codeline, especially before branching a new codeline off from the mainline. This reduces the breadth of the version tree, and keeps the level of cascading down to a bare minimum, which in turn decreases the number of transitive levels of change-propagation that are necessary.
Stable Mainline
A Stable Mainline is a mainline that is used solely as a stable-receiving line to which other stable baselines and codelines are integrated. Development never takes place on the mainline, and only stable baselines and/or stable codelines are ever merged to main. Stable Mainlines are often used in conjunction with Early Branching.
LAG Mainline
A LAG Mainline s a mainline that is used for the latest and greatest (LAG) development of the system or project. The most recent work for the very latest release/project takes place on the mainline. Work that is no longer the latest and greatest, and is not needed in the new latest efforts is branched off into its own codeline at that time for release-engineering and/or maintenance. LAG Mainlines are often used in conjunction with Deferred Branching.
Sync Mainline before Branching
Before branching a new codeline off of the mainline, some shops will insist that the mainline be "synchronized" (or "refreshed") by first integrating any outstanding codelines to mainline before spawning the new codeline's branch.
A select few shops will actually label the baseline before mainlining the release, and will then move/replace the baseline label after it has been mainlined (renaming the old baseline label before redefining the new one).
Time-Shared Mainline
Some shops employ time-sharing on the mainline. Various teams for the various releases are working in parallel on their own codeline. When it comes time for a group to merge their codeline to the mainline, that group has exclusive ownership of the mainline for the duration of the integration to main, and no other groups may checkin to the mainline at that time.
Sometimes this time-sharing takes place before the given codeline is completely stable or baselined. Intead of (or perhaps in addition to) merging the latest changes from the mainline into their codeline, they will merge their changes to the mainline for integration before baseline and release, and do their build and integration work on the mainline. This encourages a kind of "hit and run" strategy where "tiger teams" or "SWAT teams" quickly pounce on the mainline taking it over, quickly do what they need to do, and then quickly get out.
Multiple Mainlines (Alternate Mainlines)
If there is more than one variant configuration development path (either for platform-specific development paths, or for functional variants) then Multiple Mainlines (a.k.a. Alternate Mainlines) may be used. Each platform-variant or functional-variant is assigned its own mainline and serves as the "mother of all codelines" within its own particular variant.
Sometimes when several component-lines are used, the integration-line for the component or subsystem is viewed as a component-mainline within the scope of the component. But if there is a system-wide integration line that all the components eventually merge into, then the system integration line typically serves as the "mainline" from a whole-systems perspective.
Labels
Mainline Baseline
A baseline label that is applied after the corresponding versions have all been merged back to the "mainline."
Release-Line Baseline
A baseline label that is applied after the corresponding versions have integrated into the "release-line" but before any merges from the release-line to the mainline.
Change-Package or Change-Set Label
A label applied to the final set of versions checked-in for a change-task.
Task Checkpoint
A label applied to an intermediate state of the versions in a change-set or change-package. Subsequent versions may be checked-in before the change-task is complete, and the checkpoint may be used to recall a previous configuration of the task if desired.
Configuration (Config) Checkpoint
Like a "task checkpoint" only the versions needed for the developers configuration are labeled, and not just the working-set of versions being modified in the view. The config-checkpoint may take a lot longer to create. It also captures versions of elements that may have been integrated into the view, but which the developer didn't modify as part of the change-task.
Baseline VOB in View/Cspec
A baseline label that is created by applying the label to all versions in the VOB(s) that are selected in the build/integration view's config-spec. Labeling all the versions in the VOB(s) includes directory versions (or even Makefile versions) that a config-rec might (or clearmake) typically miss. It may also label versions that didn't necessarily participate in the build.
Baseline Config-Rec
A baseline label based applied to the versions indicated by the configuration-record(s) (config-recs) of the build.
Component Baseline
A Component Baseline is a baseline label created for a component or subsystem (or some other architectural subset) of the overall system or product.
Feature-Set Baseline
A Feature-Set Baseline is a baseline label created for a cohesively related set of system features or requirements (or some other functional subset) of the overall product.
Baselevel or Build-Label
A Baselevel or Build-Label is a kind of internal-use-only baseline. It corresponds to a label that is used to represent a consistent/stable configuration of the codeline, but which is not officially delivered or released or otherwise "published" outside the product development group.
Floating-Baselevel or Floating-Label
Typically, when a baseline label is created, its definition (the set of versions it labels) almost never changes once the baseline is "published" and made available to other users or developers.
A Floating-Label is a label whose definition is periodically updated. A Floating-Baselevel is a baselevel-label that is regularly updated to correspond to the most recently integrated stable state of the codeline. Its not quite as dynamic as .../LATEST, but its more dynamic than a static label definition that never changes. Some of the dynamic-update capability of the "LATEST" label is traded-off to ensure that the resulting labeled configuration is always a consistent one, but it still tries to be as dynamic as possible within that constraint.
Incremental Baselevels
In contrast to a "floating baselevel", an Incremental Baselevel does not keep the same name between baselevel definitions. Whenever the integration and build process creates a stable and consistent configuration for the codeline, a baselevel-label is created with some indication that it is the next label in a linear progression that includes its predecssors and successors (typically by some extra numeric-field at the end of the label).
It is extremely common to see "floating baselevels" used in conjunction with incremental baselevels. In this case the floating label always corresponds to the same set of versions as the most recent incremental baselevel, and the incremental baselevels record the sequence and content of stable configurations of the codeline. Sometimes the floating-label is always a separate label from the latest incremental label. And sometimes a floating label is renamed to correspond to the previous baselevel just before the floating label name is applied to the newest baselevel.
Promotion Labels
Sometimes various "promotion levels" are defined along with the linear progression from one promotion level to the next. These promotion levels may correspond to levels of testing or SQA (e.g., inspected, unit-tested, intg-tested, sys-tested, ...), or to levels of scope/scale (unit, component, subsystem, system, ...), or to levels of authority/responsibility.
One way of using promotion levels is to use a separate label per promotion level for each release or each mainline. When a version is is ready to be promoted from one level to the next, the new promotion label is applied to the version. Sometimes only one promotion-label may be on a version at a time (per release/mainline) and sometimes a version keeps all its previous promotion labels when it gets a new one (like wearing merit badges).
Label Promotion (Promoted Labels)
Promotion Labels are when there is a label for each promotion level per release/mainline. Label Promotion is when the labels get promoted, rather than the versions. Instead of having a label-per-level, a single label has a "level" or state associated with it that indicates the current promotion level of all versions referred to by that label. (One typically uses an attribute on the lbtype to indicate the promotion level, and hyperlinks might even be used to indicate predecessor and successor levels) When the versions on a codeline are deemed stable and ready to proceed to the next level, the level is associated with the label, and the label itself is what gets promoted (instead of copymerging all the versions to another label).
Configuration Records
ClearCase configuration records capture and record the set of file versions that went into a build target, including any derived objects that were generated and the build script or "recipe" used to generate each derived object and target.
Config-Rec as BOM
Some groups use config-recs primarily to serve as a bill of materials for what went into the build (kind of like a what(1) command is used to spew out SCCS or RCS versions strings in an object file). This means that the configuration-record is somehow preserved and checked-in to ClearCase (will have a baseline label applied to it when a baseline is created).
Config-Rec in Config-Spec
Some groups may also use config-recs in the config-spec of a view to reproduce the configuration of all the versions used as part of a build. This doesn't always catch the necessary versions of directories or Makefiles.
Config-Rec Comparison
Some groups use config-recs but don't necessarily version or label them. They have config-recs that are referenced by a unique-name for each build performed in the view (often with the timestamp as part of the unique-name) and use the config-recs primarily so they can execute the "diffcr" command to tell the differences between the configurations of any two builds.
Attributes
Request-ID on Checkout
An attribute corresponding to the the ID of a record in a change/defect tracking system that is applied to a version when it is checked-out.
Request-ID on Checkin
An attribute corresponding the the ID of a record in a change/defect tracking system that is applied to a version when it is checked-in.
Request-ID on Task
An attribute corresponding the the ID of a record in a change/defect tracking system that is applied to a change-task (which may be represented by a branch or a label).
Version State
An attribute indicating the state or promotion level of a version.
Branch State
An attribute indicating the state or promotion level of a branch.
Label State
An attribute indicating the state or promotion level of a label.
Change-Set Membership
An attribute indicating the name/id of the change-set (change-package) to which this element-version belongs.
Component Membership
An attribute indicating the name of the component or subsystem to which an element belongs.
Feature-Set Membership
An attribute indicating the name of the component or subsystem to which an element belongs.
Hyperlinks
Transfer Link
A hyperlink from a migration/transfer task (branch or label type) to the original task being transfered
Propagation Link
A hyperlink from a codeline to one or more codelines to propagate changes to.
Promotion Link
A hyperlink from a label or a branch to the predecessor or successor label or branch that corresponds to the next state or promotion level in a linear progression.
Task Baseline Link
A hyperlink from a change-task branch/label-type to the baseline label-type used for its development.
Task Target Baseline Link
A hyperlink from a change-task branch/label-type to the target release/baseline label-type that the change is expected to be integrated and delivered in.
Task Codeline Link
A hyperlink from a change-task branch/label-type to the codeline branch-type used for its development.
Task Target Codeline Link
A hyperlink from a change-task branch/label-type, to the target release/codeline lbtype or brtype that the change is expected to be integrated into.
Task Dependency Link
A hyperlink from a change-task branch/label-type to one or more other change-tasks upon which it depends (maybe it merged them in, or maybe it simply needed to refer to them in its config-spec).
Codeline-Baseline Link
A hyperlink between a branch-type for a codeline, and the label-type that will be applied once everything has been integrated into that codeline and the codeline is "retired."
Codeline-Mainline Link
A hyperlink from a codeline branch-type to the branch-type that serves as it's "mainline."
Triggers
pre-checkout
pre-checkout request-ID validation
pre-checkout element access verification
pre-checkout codeline access verification
pre-checkout comment verification
post-checkout
post-checkout notify
pre-checkin
pre-checkin request-ID validation
pre-checkin element access verification
pre-checkin codeline access verification
pre-checkin comment verification
post-checkin
post-checkin notify
pre-unco
pre-unco request-ID validation
pre-unco element access verification
pre-unco codeline access verification
post-unco
post-unco notification
remove /0 version on unco
remove /0 version and branch on unco .../branch/1 version
remove /0 version and element on unco of /main/1 version
pre-rmver
prevent version removal by ordinary users
pre-rmname
prevent element entry removal from directories by ordinary users
pre-rmbranch
prevent branch removal by ordinary users
pre-rmtype
prevent type (lbtype, brtype, etc.) removal by ordinary users
pre-rmelem
prevent element removal by ordinary users
pre-mkelem
prevent parallel creation of different files with the same name in the same directory
post-mkelem
modify the protections of newly created elements to give them the appropriate owner and group and read/write access permissions.
pre-mkbrtype
prevent branch-type creation by ordinary users
enforce branch-naming conventions
require comment on branch-creation
post-mkbrtype
attach branch-type attrs/hlinks on creation
pre-mklbtype
prevent label-type creation by ordinary users
enforce label-naming conventions
require comment on label-creation
post-mklbtype
attach label-type attrs/hlinks on creation
pre-mklabel
prevent labeling by ordinary users
pre-mktrtype
prevent trigger creation by ordinary users
pre-mkattype
limit attribute-type creation by ordinary users
pre-mkattr
limit attribute value assigment by ordinary users
post-mkattr
notification of attribute value changes
pre-submit (simulated)
simulate a pre-op trigger for completion/submission of a change-task as a single logical change-set.
post-submit (simulated)
simulate a post-op trigger for completion/submission of a change-task as a single logical change-set.
pre-mkview (simulated)
simulate a pre-op trigger for view creation
post-mkview (simulated)
simulate a post-op trigger for view creation
pre-rmview (simulated)
simulate a pre-op trigger for view removal
post-rmview (simulated)
simulate a post-op trigger for view removal
cmd-trigger (simulated)
simulate pre-op/post-op triggers for entire commands (rather than individual events)
Locks
task-lock
lock task branch against changes by non-owner
lock task branch/label type against changes after completed submission
integration/merge lock
lock integration lines against checkin by non-integrators
mainline lock
lock mainline against checkin by ordinary users
baselevel lock
lock baseline label definitions after baselining
floating label lock
lock floating labels against change by ordinary users
metadata lock
lock metadata (attributes and hyperlinks) against changes by ordinary users (unless performed automatically by triggers)
element lock
lock elements against modification by unauthorized users
component lock
lock "components" or "subsystems" against modification by unauthorized users
VOB lock
lock entire VOBs against access by unauthorized users
Multi-Site
Tool-Supported Roles/States
branch roles
branch states
component/subsystem roles
component/subsystem states
integration roles
integration states
build roles
build states
release roles
release states
administration roles
administration states
VOB Management
VOB naming conventions
Use of Admin VOBs
VOB per group
VOB per product
Multiple VOBs per product
VOBs shared by multiple products
VOBs shared by multiple groups
Separate VOB for documents
Separate VOB for externally supplied files
Separate VOB for tools and libraries
View Management
view naming conventions
users create their own views
tool creates user's views
users decide where to store their views
tool decides where to store user views
policies specifying viewstorage usage/locations
users can chmod/chgrp/chown their views
shared views (multiple developers in same view)
one developer per view
dedicated integration/build views
dedicated release views
view per task
view per developer
viewpool or upperbound on number of active views
view seeding
View seeding is a way of "pre-populating" a view with the needed derived object to speedup subsequent builds and winkins.
Config-Spec Management & Version Selection
users create their own initial cspecs
tool creates initial cspecs
users modify their own cspecs
tools modify user's cspecs
dynamic version selection
Some shops have developer's config-specs select the /LATEST versions on the codeline. As soon as they are checked in to the codeline, the developers may see them in their views. This can be more problematic if online development is permitted than if all work is done on task-branches.
static version selection
Some shops expressly do not select the /LATEST versions on the codeline. Instead, the select only the most recently labeled baselevel of the codeline.
static file versions but dynamic directories
Some shops will use static version selection for files, selecting the versions on a labeled baselevel, but use dynamic selection for directories (using a '-directory' rule to select the /LATEST versions on the codeline for directory elements). This lets developers always see the latest version of a directory in the codeline, and avoids collisions resulting from creating files by the same name on different branches. If a new file has been created by someone else, they will see the new file in their view, but not necessarily its contents.
selection of /main/0
Some groups (especially those that dont work directly on /main) will always insert a rule at the end of a config-spec that selects the /main/0 version of any file or directory not yet selected. This lets them see files and directories created in some other branch so they dont create colliding file or directory elements.
Version Management
of source code
of auto-generated source code
of derived object files
of built executables
of built libraries
of environment/options settings
of documents
of program data inputs/outputs
of test cases, test vectors, or test results
of build tools (compilers, linkers, debuggers)
of externally supplied libraries
of externally supplied and system header files
of externally supplied source code
of externally supplied binaries/images
Integration with Tracking System
on element creation
on version checkout
on version checkin
on uncheckout
on branch-type creation
on branch creation
on label-type creation
on label-creation
performer-verification
Verify that a particular ClearCase action (e.g., checkin/checkout or creation of a branch-type or label-type) is performed only by the user that is assigned or authorized to perform that action as declared in the corresponding change-request record.
on record state transitions
ClearCase data obtained from issue/task record
Target-Release defines Config-Spec
The target-release specified for a record in the tracking system is used to define or enforce the codeline and/or baseline (branch and/or label) used for development in the view's config-spec.
ClearCase data logged to issue/task record
Separate record-type for defects
Separate record-type for feature requests/development
Separate record-type for build/integration requests
Separate record-type for inspections/reviews
Separate record types for document changes
Document Management
Document naming conventions
Document ID naming conventions
Document location conventions
Concurrent Development for documents
Release Management
Release naming conventions
Release numbering conventions
Target-Release per Change/Feature
Every record for every change-request, bugfix, or feature/enhancement request is required to estimate an intended target release for the proposed change.
Integration approval per Request/Feature
Some shops require CCB approval before allowing integration of a requested feature, fix, or enhancement into a release-codeline. Approval is mode at the level of a given feature or function to decide not only if it should be integrated, but more importantly which release codeline/baseline it should be integrated into (possibly changing previous plans for the targeted baseline/release).
Integration approval per Change-Task
Some shops require CCB approval before allowing integration of any completed change-task into a release-codeline. Approval is mode at the level of a given task or subtask to decide not only if it should be integrated, but more importantly which release codeline/baseline it should be integrated into (possibly changing previous plans for the targeted baseline/release).
Access Control/Restrictions
Restrictive Code-Ownership
Subsystems and/or Modules of code are assigned a single owner responsible for their integrity, and no one but the code-owner is allowed to checkout (and/or checkin) a piece of code. This actually applies to other artifacts besides source-code, including documents and tests.
Relaxed Code-Ownership
Subsystems and/or Modules of code are assigned a single owner responsible for their integrity, and developers other than the code-owner are permitted to checkout (and/or checkin) a piece of code provided that they have permission from the code-owner. This actually applies to other artifacts besides source-code, including documents and tests.
Restrictive Codeline-Ownership
Individual Codelines are assigned to a single owner responsible for its integrity and no one but the codeline-owner is allowed to checkout from (and/or checkin to) the codeline.
Relaxed Codeline-Ownership
Individual Codelines are assigned to a single owner responsible for its integrity anddevelopers other than the codeline-owner are permitted to checkout from (and/or checkin to) the codeline provided that they have permission from the codeline-owner
Change Control Boards
CCB per component/team
Product-wide Software CCB
System-level CCB (includes both hardware and software)
Business-level CCB
Work approval per Request/Feature
Some shops require CCB approval for a request feature, fix, or enhancement before effort has been made to breakdown the proposed work into tasks and subtasks. Approval is mode at the level of a given feature or function. Subsequent approval of the constituent tasks needed to implement the functionality may or may not take place, and rejection of a task or subtask may change the current accept/reject status of the corresponding feature or fix.
Work approval per Change-Task
Many shops require a proposed change to obtain CCB approval before any development work can begin on that change. This is often done an a per-task basis, requiring approval for each planned development task (possibly including subtasks) for a given feature or request.
Introduction
This page attempts to catalog common practices with the ClearCase software configuration management tool. At present, no attempt is made to distinguish which practices are "good"and which ones aren't. At a later date, I hope to be able to sort the common usage patterns listed here into "best practices"and "traps and pitfalls."
I hope to determine this by having people from various development shops answer the following questions for each practice that they actually use:
* Do they consider it a "best-practice"? Why or why not? (what is the rationale)
* What is the underlying problem the practice solves for them?
* What are the benefits they see resulting from its use?
* What are the drawbacks (tradeoffs) they see? How are they handled?
* What circumstances make this a "best-practice" for them that might make the practice inappropriate under different project conditions?
* What were the motivating factors that made this alternative more attractive than others that might have been considered?
* What related practices do they use that depend upon (or are depended upon by) this one?
Currently, the practices are partitioned into the following areas (with some overlap):
o Branches
o Labels
o Configuration Records
o Attributes
o Hyperlinks
o Triggers
o Locks
o Multi-Site
o Tool-Supported Roles/States
o VOB Management
o View Management
o Config-Spec Management & Version Selection
o Version Management
o Integration with Tracking System
o Document Management
o Release Management
o Access Control/Restrictions
o Change Control Boards
Branches
* Branch Naming Conventions
* Task Branches
* Integration Branches
* Release Branches
Early Branching
Early Branching is when codelines for new development or integration are created right away, as soon as any work on the corresponding project or release begins. This is often used when the mainline is a "Stable Receiving Line" reserved only for merges of baselines. New codelines are spawned off the mainline as soon as the corresponding work begins.
For example, if work on release 1.0 has completed and work on 1.1 is taking place, and at the same time, work on release 2.0 is about to start, then a new codeline is branched off mainline for work on release 2.0 at that point (and if it isn't already, work on release 1.1 and other version 1 maintenance releases) goes on its own branch.
Thus Early Branching merges into mainline with the old baseline, and then branches out from mainline for the new development/release.
Deferred Branching
In contrast to "Early Branching", Deferred Branching (also called Lazy Branching) is when branch creation for new development/integration codelines is put off until the last minute. This is often used when the mainline is a "Latest and Greatest Development Line" (or "LAG Line"). The latest and greatest development work takes place on the mainline, or the main development line (which might not be /main), and codelines are branched off only when the corresponding work is no longer the latest and greatest.
For example, when working on release 1.0, development happens on the mainline. Work on 1.1 and 1.2 (and 1.x) also happens on the mainline until work on the next release (2.0) starts to take place in parallel. At that point, development for release 2.0 takes over the mainline, and then a separate branch is created for maintenance work on release 1.x.
Thus, instead of branching for a new release-line as soon as work begins on the release, we wait to branch it off mainline, until it goes into maintenance mode or until development on a subsequent release begins in parallel from existing work. At which time its out with the old (it gets a new codeline branched out from main) and in with the new (the new development work comes in on the mainline).
The reasoning here is that by branching later rather than earlier, there is a single codeline for a longer period of time and changes simply get merged into the single codeline instead of having to get merged into two parallel codelines. Once the second codeline is split off from the first (regardless of early or late creation), then changes made in the newly branched codeline often need to be propagated back to the parent codeline somehow (either my merging the changes themselves, or by merging the codeline to its parent to "synch-up"). This is a trade-off of safety in favor of liveness (productivity): by waiting longer before splitting off a new codeline, the amount of propagation and synch-ing effort is reduced, at the risk of having less separation/isolation of change.
Directory Branching
Some shops avoid branching directories in ClearCase because when directories are created on a branch, or their contents are altered on a branch (a file is added or removed to its list of elements), they sometimes run into problems with visibility of elements, often resulting in the same element being created twice on different branches.
Other shops use branches for directories in the same way they would for any other elements. And if they have a reasonably organized and disciplined and consistent use of branching, and are sure to integrate early and often, they tend not to suffer too much from the aforementioned problems.
Branch Naming Conventions
Many groups use specific naming conventions for the various kinds of branches that are created. There will typically be some portion of the name that indicates the type of branch (release-line, component-line, integration-line, fix/feature). If the branch corresponds to a major or minor release, then the release number is usually included. If it corresponds to a record in a tracking database, the database-ID of the record is often part of the branch name as well. Some may also employ the primary developer's username as part of the branch-name.
Branch Type Prefix
Use of a prefix to indicate the type/purpose of a branch (e.g., "rel", "int", "fix", "feat", "dev", "tst", "comp", "prod", "proj", etc.)
Release ID in Branch Name
Use of the major and/or minor release version in a branch name (e.g., "rel1", "rel1.2", "rel2.X").
Request ID in Branch Name
Use of change requests tracking systems corresponding request ID as all or part of the branch name (e.g., "cr123", "bug243", "feat331").
User ID in Branch Name
Use of sole or primary developer's username as all or part of the branch name (e.g., "calvin", "hobbes_bug243", "suzy_feat331").
Component ID in Branch Name
Use of a component-name or subsystem-name as all or part of the branch name (e.g., "GUI_rel2.6", "MMI", "ACG-1234").
Task purpose in Branch Name
Use of an indentifier corresponding to the purpose of the task as all or part of the branch name (e.g., "flush_on_write", "fix1234_confirm-exit").
Task Branches
A Task Branch is a branch that is used only for development of a single task. When the task is completed and the changes have been tested in isolation, then the change-task branch is merged into the integration branch (usually its parent). After the change-task is completed or integrated, its not uncommon for it to be "locked down" (retired) from any future changes.
If all change-tasks must be performed on their own task-branch, this is called the Branch per Task approach. Some groups instead prefer to use a Branch per Major Task creating task branches only for more involved (higher risk or longer-lived) efforts, and performing short and (seemingly) simple tasks "on-line" (directly on the codeline instead of on a separate task-branch).
Fix Branch
A Fix Branch is a task branch created for the purpose of fixing a "bug" in the software.
Branch per Request
This is basically the same thing as "Branch per Task". The main difference is that in this case, branches are only created for formal requests logged in a bugtracking and/or change-request tracking database, and other untracked change-tasks might or might not have their own task-branch.
Feature Branch
One of the more common uses of codelines is to house development work for a specific major or minor release (minor releases are sometimes called "point releases" because they only affect the number after the first "point" in the version name/number). Some groups also use branches to shore up work in major or minor system features, (possibly independent of which release-line they may end up getting merged to).
It's common for a group to use task-branches for enhancements and bugfixes that stem from change-requests and/or bug-reports. Its less common to see this same philosphy applied to initial feature development as well (before an initial baseline is created), or before a codeline goes from pure development mode maintenance (and development) mode.
With feature branches, "feature" tasks are created in the tracking system that correspond to new development features to implement in the next or current release. Some of these features may encompass more than a single discrete development task, but often they will correspond to a single task. (In the case of the former, the feature branch may turn out to be a special kind of subproject line called a "feature line" - feature lines typically are smaller units of functionality than "functional lines").
Private Task-Branches
A "private" task branch is a task-branch that is specifically locked right after creation so that only the assigned individual developer make checkout/checkin any versions on the branch. Sometimes groups simply use "private branches" by explicit convention, but don't actually enforce them using ClearCase locks or triggers.
Shared Task-Branches
A "shared" task branch is a task-branch that is deliberately planned and used for development by two or more people on the same branch and task. This may take place in separate views for each developer, or the developers might use a shared view (to conserve diskspace and network reources) if they can obey conventions to prevent each other from modifying the same sets of files (or at least at the same time).
Task-Migration Branch (a.k.a. Transfer-Branch, Carry-over branch)
A Task-Migration branch (or Carry-over branch) is a change-task branch that is created to propagate a change task from one "mainline" to another "mainline." When a group is using multiple mainlines which are long-lived (sometimes each mainline is a different functional-variant line) then change-tasks made in one mainline often need to be propagated to one or more other mainlines. Since the context in which the original change-task occurred may include things that were specific to its particular variant or configuration, a separate migration branch is created for each mainline to receive the propagated change. This keeps the changes isolated on a separate branch of the new mainline so they can be merged, integrated, and stabilized, before adversely impacting other users of the mainline.
Its not uncommon for task-migration branches to require a partial ordering in their integration to a given mainline. Tasks from the same mainline usually need to be propagated to other mainlines in the same order they were completed in their initial mainline (unless the tasks are completely independent and don't share any common context besides a common baseline).
Codeline-Owner as Integrator
The Codeline-Owner serves as the integrator and is responsible for merges all Task-Branches into the codeline. When development is completed on a task-branch, it has to get merged to the integration codeline. Sometimes this is done at periodic intervals by a special "codeline integrator" who is responsible for performing all integrations into their codeline and maintaining a consistent state.
If done right, it works swell. If done wrong, it can result in a "throw it over the integration wall" scenario where there is very little and/or infrequent communication or cooperation between developers and integrators and working relations between them can become very strained and unproductive. It also makes it harder for each group to appreciate the work and needs of the other and they will frequently resist changes to their own work-habits for the benefit of the other group if they can't perceive any benefit to their own group.
Merge Your Own Code/Change
This is when developers are responsible for merging their own change-tasks back into the codeline. It is usually done as soon as the individual task is completed (including after code-review and unit-test).
If done right and with discipline, this too can work out just great. If done wrong, you can have haphazard changes integrated at irregular times, and consistency and stability of the codeline can be next to impossible to rely upon. Regardless of whether developers or separate integrators merge changes to the codeline, there needs to be a responsible "codeline owner" who takes to heart the duty of ensuring that changes are merged in an organized manner and frequency, and that the codeline is as consistent and stable as possible at all times.
Sync Before Merging (sync before export, pre-merging)
Some shops encourage or require developers to merge the latest state of the codeline into their task branch and view before allowing the change to be integrated to the codeline. This ensures that the merge to the codeline will always be a trivial one (provided its performed very shortly thereafter or else in a controlled order) regardless of whether the merge to the codeline is performed by the developer or an integrator.
The downside of this is decreased separability of the change-task from its initial baseline/context. If any merges were made to files on the task-branch, then the branch now contains (and may depend upon) more changes than just the task plus the baseline it was first branched off from. Backing out such changes can be harder to locate or disentangle unless other measures are taken (like checkpointing the versions on the branch before syncing-up with the codeline). The likelihood of merge problems to be handled by an integrator is often decreased because changes are merged by the developers who made them, and codeline integration is usually trivial. But when a problem does occur, its likely to be more of a hassle to resolve.
The main issue has to do with whether the particular environment makes developers more or less likely to be as familiar with the latest state of the codeline as they are with their own changes. If they are, then the developer is typically best suited to do the merging; otherwise the codeline-owner is usually the better choice (and sometimes you need both :-)
Integration Branches
An Integration Line is a branch that is used primarily, or even exclusively for performing integrations of incoming changes. Some like to make the distinction between an "integration line" versus an "integration "branch" (or "integration-task branch"). They use the term Integration Line to refer to a codeline that is created in advance, ahead of many of the changes that will be integrated. When a change is made on its own task-branch, after the change is debugged and tested, it then gets merged into the already created integration line. So the integration-line lives on after the merged task-branch is completed and remains active to in order to merge many other task-branches as they start and finish during the lifetime of the integration-line.
Integration-Task Branch
In contrast to an Integration Line, an Integration-Task Branch typically doesn't get created until after most of the development changes to integrate have already begun, and often isn't created until most of the development changes are ready to be merged. The "integration-task branch" is then created (and sometimes the codeline is frozen from further development changes until the integration is completed). The integrator then merges in each of the ready-to-be-merged development changes in rapid succession (hopefully in some intelligent order based on change-dependencies). So the lifetime of an integration-task branch usually doesnt span over multiple task-branches; it typically doesnt start until most of the task-branches are well underway and ready for integration.
On-line Development (development allowed on integration line)
Some groups allow developers to checkout/checkin on the integration line. It may be that all development happens on the integration line until an initial baseline is created and/or the codeline goes into "maintenance mode." Or else developers perform minor change-tasks "online" using task-branches only for what they consider "major" changes.
Off-line Development (development only on task-branches)
Some groups forbid development tasks on the integration-line, reserving it only for integration of task-branches (which might be performed by an integrator, or by the developer).
Platform Lines (branching for platform variants)
This is a codeline created to house platform-specific work of the system. It might be for a different operating system, or different hardware, or a different windowing environment. But code specific to the particular operating environment has its own platform-speficic integration line.
The more commonly recommended way to handle this is to use platform specific subdirectories and files. Rather than use a sea of #ifdefs to create conditionally compiled spaghetti code, platform-specific code is split out into separate compilation units in a subdirectory named after that platform (or the platform might be a prefix in the filenames). Then a variable can be used in the Makefile(s) to select the specific platform files and directories.
Platform-directories are usually preferred over platform-branches, but occasionally one runs into cases where platform-branches really do seem to make sense.
Feature-Set Lines (Functional Lines)
If the product being constructed has several different functional variants that need to be built, then either each functional variant is given its own codeline; or else each major function that may be varied is given its own codeline and then the versions from the appropriate mix of functional lines is configured to form the desired functional variant of the product.
Component Lines
Sometimes the system is partitioned up into an explicit list of component or subsystems. And a separate team is often assigned to work on each component. It's not uncommon for each component team to create its own component development barnch as the main integration branch for the component, and then development for the component takes place on the component line, or else on one of its sub-branches and is eventually integrated to the component line.
Baselined versions of each of the various components are usually integrated together to configure a complete system build. Sometimes this is done by having each component line merge its latest state into a system-wide integration line, sometimes it's done simply by integrating in the LATEST versions on each components, and sometimes its done simply by selecting the appropriate baseline label for each component in the config-spec (there is rarely ever any overlap between the sets of files making up a given component).
The difference between a "component line" and a "functional line" is that a functional line is for a variant piece of functionality that is not always part of every released configuration. Whereas a "component" line is reserved for work on a particular subsystem regardless of whether or not it is always released with every configuration.
Subproject Lines
A project line may be thought of as virtually any branch or codeline created for one or more related tasks with a common goal. A release-line (the main development or integration line for a specific release) can be thought as a project line whose goal is to deliver a particular release.
It is extremely common for groups to have a main integration line for their work on a particular release (or project), and for all other work to take place other directly on the release-line, or else on a single branch off the release-line for a single task (a bugfix or enhancement) which then gets merged into the main integration line upon completion.
A Subproject Line is a codeline branched off the main integration line that is used for work which spans more than one development task (and hence more than one "task-branch"). Sometimes two or three people work on interdependent tasks on their own separate branches. Rather than each referring directly to the others branch in their configurations, the create a common subproject integration line for their work, and refer to the subproject line instead of someone else's task branch. When someone needs the latest state of someone else's branch, they ask that person to merge to the subproject branch. When all the interdependent tasks are finished and integrated to the subproject branch, then the subproject branch is ready to be merged back to the main integration line.
So a common indicator of a subproject line is when branches are more than one level deep off the main integration line for the release or project codeline. It helps avoid the scenario of "spaghetti branching" where individual task branches explicitly depend on other task branches in a haphazard fashion, much like the haphazard use of unstructured gotos in a program leads to spaghetti code.
Third-Party Line (Vendor Line, Vendor Branch)
When source-code (or other kinds of files) are supplied by some external third-party vendor or supplier and require local modifications they need to be version controlled. The problem is that this needs to be done in a way that minimizes integration effort when obtaining a new release of files from the supplier while accommodating local changes that had to be made.
The common approach to this problem is to use a Third-Party Line or Vendor Branch. Rather than trying to maintain both the vendor-supplied versions and the locally modified versions on the same codeline, a separate codeline is used to hold only the vendor supplied releases of the files. The first time the files are received, the vendor line is created separate from the local development branch (which one branches off of which isn't a big deal, it can happen either way). Then local changes are made on the local development line. When a new release is received, it is checked-in to the vendor-line, and then merged (integrated) into the local development line.
Staged Integration Lines (Promotion Branches)
Sometimes various "promotion levels" are defined along with the linear progression from one promotion level to the next. The criteria used to decide what constitutes a "promotion level" and when to promote something to the next level may vary widely depending on how the group chooses to define them. These promotion levels may correspond to levels of testing or SQA (e.g., inspected, unit-tested, intg-tested, sys-tested, ...), or to levels of scope/scale (unit, component, subsystem, system, ...), or to levels of authority/responsibility.
One way of using promotion levels is to use a separate integration line per promotion level for each release or each mainline. When a version is merged from one promotion branch to its successor, it has been "promoted" to the new level.
Codeline Promotion (Branch Promotion, Promoted Branches)
Staged Lines is when there is a promotion branch for each promotion level. Codeline Promotion (or Branch Promotion) is when the branches get promoted, rather than the versions. Instead of having a branch-per-level, a single codeline has a "level" or state associated with it that indicates the current promotion level of all versions on that branch-type. (One typically uses an attribute on the brtype to indicate the promotion level, and hyperlinks might even be used to indicate predecessor and successor levels). When the versions on a codeline are deemed stable and ready to proceed to the next level, the level is associated with the branch, and the branch itself is what gets promoted (instead of copymerging all the versions to another branch).
Change Propagation
This deals with propagating changes from other integration branches. If a change is made in one codeline that is needed in another codeline (for example, a bugfix in release 1.0 might happen on the release 1.1 codeline, and the fix also needs to find its way into the release 2.0 codeline), some groups simply wait for some (possibly long) durations before merging those changes from one codeline to the other.
Other groups however will propagate changes early and often, syncing up the changes in one codeline (e.g. the rel-1.1 codeline) with the other codeline (e.g. the rel-2.0 codeline) at regular and frequent intervals (sometimes per-task, other times daily, or weekly).
Release Branches
A Release Branch is a codeline reserved for work towards a particular release or a major release. Usually the release codeline is a kind of integration branch. Sometimes a Release Codeline will have its own separate integration branch, but that is relatively rare.
Major Release Line
A major release codeline is one that would be created for all releases with the same major version number (e.g. 1.0, 1.1, ..., 1.x). So a release 1.x codeline would be used for integration (and/or development) of all features for release 1 and all its subsequent maintenance releases and patches. If early branching was used, the major release line is created right away. Otherwise if lazy (deferred) branching was used, it might not be created until just before or just after the initial major release of that code (in which case most of the development happened on a LAG mainline, and the branch was created for release engineering and integration as well as for subsequent maintenance).
Codeline per Release
This is when a release branch is created for every release (major and minor). More often than not, each release-line is branched off from the mainline (possibly after syncing up the mainline with other release lines first, to "refresh" it with the latest baselines before branching off of it - this helps avoid continually cascading release lines off release lines).
Sometimes a release-line is branched off the major release line for each specific release (instead of from the mainline). In this case the Major release-line may serve as either a "Stable Receiving Line" if Early Branching is used, or a "LAG development line" if Deferred Branching is used.
Codeline per Major Release
Sometimes major-release lines are always created, and branches are only created for a specific release of the major-release in the event they seem absolutely necessary for a bigger/tougher than usual release engineering effort (in which case they are often quickly merged back to the major release-line when finished).
Patch Line
In addition to branching for major or minor releases, sometimes a separate branch is created for a specific patch-effort. The effort might simply be for a single task that results in a released "patch", or it might be more long-lived over several tasks (usually for a limited period of time, like a month or two) and results in a released patch (possibly before or after merging it back to the release-line).
The more common case is where code on the patch-line is released only after everything on the patch-line has been integrated and baselined. However some groups that need to very quickly respond to a set of internal or "in house" users will use the patch-branch (and its corresponding workspace) as a kind of emergency patch-release area to quickly push out incremental fixes to a recent release.
Mainline
A mainline is kind of a "homing line" or "anchor" for all other paths of development branched off from it. If there is only one persistent variant of the code (e.g. no platform-lines nor functional-lines are needed) then only one mainline is usually required. (And in ClearCase this will almost always be "/main".)
Mainlines are typically used primarily for integration, and serve as a stable receiving line; or else they are used as the primary LAG development line. Some groups even use a LAG development mainline that gets periodically merged to an integration mainline.
Mainlines serve as the main-stream from all other major codelines are branched. And every major codeline eventually must merge back to the mainline at periodic intervals and/or before retiring/decommissioning the major codeline. This helps avoid the "continuing cascade problem" where each release-line branches of from its predecessor release, and the predecessor has to propagate its changes to its successor, resulting in a very deep and wide propagation of changes from release-line to release-line with no end in sight.
Using a mainline causes all child codelines to regularly merge back to their common parent codeline, especially before branching a new codeline off from the mainline. This reduces the breadth of the version tree, and keeps the level of cascading down to a bare minimum, which in turn decreases the number of transitive levels of change-propagation that are necessary.
Stable Mainline
A Stable Mainline is a mainline that is used solely as a stable-receiving line to which other stable baselines and codelines are integrated. Development never takes place on the mainline, and only stable baselines and/or stable codelines are ever merged to main. Stable Mainlines are often used in conjunction with Early Branching.
LAG Mainline
A LAG Mainline s a mainline that is used for the latest and greatest (LAG) development of the system or project. The most recent work for the very latest release/project takes place on the mainline. Work that is no longer the latest and greatest, and is not needed in the new latest efforts is branched off into its own codeline at that time for release-engineering and/or maintenance. LAG Mainlines are often used in conjunction with Deferred Branching.
Sync Mainline before Branching
Before branching a new codeline off of the mainline, some shops will insist that the mainline be "synchronized" (or "refreshed") by first integrating any outstanding codelines to mainline before spawning the new codeline's branch.
A select few shops will actually label the baseline before mainlining the release, and will then move/replace the baseline label after it has been mainlined (renaming the old baseline label before redefining the new one).
Time-Shared Mainline
Some shops employ time-sharing on the mainline. Various teams for the various releases are working in parallel on their own codeline. When it comes time for a group to merge their codeline to the mainline, that group has exclusive ownership of the mainline for the duration of the integration to main, and no other groups may checkin to the mainline at that time.
Sometimes this time-sharing takes place before the given codeline is completely stable or baselined. Intead of (or perhaps in addition to) merging the latest changes from the mainline into their codeline, they will merge their changes to the mainline for integration before baseline and release, and do their build and integration work on the mainline. This encourages a kind of "hit and run" strategy where "tiger teams" or "SWAT teams" quickly pounce on the mainline taking it over, quickly do what they need to do, and then quickly get out.
Multiple Mainlines (Alternate Mainlines)
If there is more than one variant configuration development path (either for platform-specific development paths, or for functional variants) then Multiple Mainlines (a.k.a. Alternate Mainlines) may be used. Each platform-variant or functional-variant is assigned its own mainline and serves as the "mother of all codelines" within its own particular variant.
Sometimes when several component-lines are used, the integration-line for the component or subsystem is viewed as a component-mainline within the scope of the component. But if there is a system-wide integration line that all the components eventually merge into, then the system integration line typically serves as the "mainline" from a whole-systems perspective.
Labels
Mainline Baseline
A baseline label that is applied after the corresponding versions have all been merged back to the "mainline."
Release-Line Baseline
A baseline label that is applied after the corresponding versions have integrated into the "release-line" but before any merges from the release-line to the mainline.
Change-Package or Change-Set Label
A label applied to the final set of versions checked-in for a change-task.
Task Checkpoint
A label applied to an intermediate state of the versions in a change-set or change-package. Subsequent versions may be checked-in before the change-task is complete, and the checkpoint may be used to recall a previous configuration of the task if desired.
Configuration (Config) Checkpoint
Like a "task checkpoint" only the versions needed for the developers configuration are labeled, and not just the working-set of versions being modified in the view. The config-checkpoint may take a lot longer to create. It also captures versions of elements that may have been integrated into the view, but which the developer didn't modify as part of the change-task.
Baseline VOB in View/Cspec
A baseline label that is created by applying the label to all versions in the VOB(s) that are selected in the build/integration view's config-spec. Labeling all the versions in the VOB(s) includes directory versions (or even Makefile versions) that a config-rec might (or clearmake) typically miss. It may also label versions that didn't necessarily participate in the build.
Baseline Config-Rec
A baseline label based applied to the versions indicated by the configuration-record(s) (config-recs) of the build.
Component Baseline
A Component Baseline is a baseline label created for a component or subsystem (or some other architectural subset) of the overall system or product.
Feature-Set Baseline
A Feature-Set Baseline is a baseline label created for a cohesively related set of system features or requirements (or some other functional subset) of the overall product.
Baselevel or Build-Label
A Baselevel or Build-Label is a kind of internal-use-only baseline. It corresponds to a label that is used to represent a consistent/stable configuration of the codeline, but which is not officially delivered or released or otherwise "published" outside the product development group.
Floating-Baselevel or Floating-Label
Typically, when a baseline label is created, its definition (the set of versions it labels) almost never changes once the baseline is "published" and made available to other users or developers.
A Floating-Label is a label whose definition is periodically updated. A Floating-Baselevel is a baselevel-label that is regularly updated to correspond to the most recently integrated stable state of the codeline. Its not quite as dynamic as .../LATEST, but its more dynamic than a static label definition that never changes. Some of the dynamic-update capability of the "LATEST" label is traded-off to ensure that the resulting labeled configuration is always a consistent one, but it still tries to be as dynamic as possible within that constraint.
Incremental Baselevels
In contrast to a "floating baselevel", an Incremental Baselevel does not keep the same name between baselevel definitions. Whenever the integration and build process creates a stable and consistent configuration for the codeline, a baselevel-label is created with some indication that it is the next label in a linear progression that includes its predecssors and successors (typically by some extra numeric-field at the end of the label).
It is extremely common to see "floating baselevels" used in conjunction with incremental baselevels. In this case the floating label always corresponds to the same set of versions as the most recent incremental baselevel, and the incremental baselevels record the sequence and content of stable configurations of the codeline. Sometimes the floating-label is always a separate label from the latest incremental label. And sometimes a floating label is renamed to correspond to the previous baselevel just before the floating label name is applied to the newest baselevel.
Promotion Labels
Sometimes various "promotion levels" are defined along with the linear progression from one promotion level to the next. These promotion levels may correspond to levels of testing or SQA (e.g., inspected, unit-tested, intg-tested, sys-tested, ...), or to levels of scope/scale (unit, component, subsystem, system, ...), or to levels of authority/responsibility.
One way of using promotion levels is to use a separate label per promotion level for each release or each mainline. When a version is is ready to be promoted from one level to the next, the new promotion label is applied to the version. Sometimes only one promotion-label may be on a version at a time (per release/mainline) and sometimes a version keeps all its previous promotion labels when it gets a new one (like wearing merit badges).
Label Promotion (Promoted Labels)
Promotion Labels are when there is a label for each promotion level per release/mainline. Label Promotion is when the labels get promoted, rather than the versions. Instead of having a label-per-level, a single label has a "level" or state associated with it that indicates the current promotion level of all versions referred to by that label. (One typically uses an attribute on the lbtype to indicate the promotion level, and hyperlinks might even be used to indicate predecessor and successor levels) When the versions on a codeline are deemed stable and ready to proceed to the next level, the level is associated with the label, and the label itself is what gets promoted (instead of copymerging all the versions to another label).
Configuration Records
ClearCase configuration records capture and record the set of file versions that went into a build target, including any derived objects that were generated and the build script or "recipe" used to generate each derived object and target.
Config-Rec as BOM
Some groups use config-recs primarily to serve as a bill of materials for what went into the build (kind of like a what(1) command is used to spew out SCCS or RCS versions strings in an object file). This means that the configuration-record is somehow preserved and checked-in to ClearCase (will have a baseline label applied to it when a baseline is created).
Config-Rec in Config-Spec
Some groups may also use config-recs in the config-spec of a view to reproduce the configuration of all the versions used as part of a build. This doesn't always catch the necessary versions of directories or Makefiles.
Config-Rec Comparison
Some groups use config-recs but don't necessarily version or label them. They have config-recs that are referenced by a unique-name for each build performed in the view (often with the timestamp as part of the unique-name) and use the config-recs primarily so they can execute the "diffcr" command to tell the differences between the configurations of any two builds.
Attributes
Request-ID on Checkout
An attribute corresponding to the the ID of a record in a change/defect tracking system that is applied to a version when it is checked-out.
Request-ID on Checkin
An attribute corresponding the the ID of a record in a change/defect tracking system that is applied to a version when it is checked-in.
Request-ID on Task
An attribute corresponding the the ID of a record in a change/defect tracking system that is applied to a change-task (which may be represented by a branch or a label).
Version State
An attribute indicating the state or promotion level of a version.
Branch State
An attribute indicating the state or promotion level of a branch.
Label State
An attribute indicating the state or promotion level of a label.
Change-Set Membership
An attribute indicating the name/id of the change-set (change-package) to which this element-version belongs.
Component Membership
An attribute indicating the name of the component or subsystem to which an element belongs.
Feature-Set Membership
An attribute indicating the name of the component or subsystem to which an element belongs.
Hyperlinks
Transfer Link
A hyperlink from a migration/transfer task (branch or label type) to the original task being transfered
Propagation Link
A hyperlink from a codeline to one or more codelines to propagate changes to.
Promotion Link
A hyperlink from a label or a branch to the predecessor or successor label or branch that corresponds to the next state or promotion level in a linear progression.
Task Baseline Link
A hyperlink from a change-task branch/label-type to the baseline label-type used for its development.
Task Target Baseline Link
A hyperlink from a change-task branch/label-type to the target release/baseline label-type that the change is expected to be integrated and delivered in.
Task Codeline Link
A hyperlink from a change-task branch/label-type to the codeline branch-type used for its development.
Task Target Codeline Link
A hyperlink from a change-task branch/label-type, to the target release/codeline lbtype or brtype that the change is expected to be integrated into.
Task Dependency Link
A hyperlink from a change-task branch/label-type to one or more other change-tasks upon which it depends (maybe it merged them in, or maybe it simply needed to refer to them in its config-spec).
Codeline-Baseline Link
A hyperlink between a branch-type for a codeline, and the label-type that will be applied once everything has been integrated into that codeline and the codeline is "retired."
Codeline-Mainline Link
A hyperlink from a codeline branch-type to the branch-type that serves as it's "mainline."
Triggers
pre-checkout
pre-checkout request-ID validation
pre-checkout element access verification
pre-checkout codeline access verification
pre-checkout comment verification
post-checkout
post-checkout notify
pre-checkin
pre-checkin request-ID validation
pre-checkin element access verification
pre-checkin codeline access verification
pre-checkin comment verification
post-checkin
post-checkin notify
pre-unco
pre-unco request-ID validation
pre-unco element access verification
pre-unco codeline access verification
post-unco
post-unco notification
remove /0 version on unco
remove /0 version and branch on unco .../branch/1 version
remove /0 version and element on unco of /main/1 version
pre-rmver
prevent version removal by ordinary users
pre-rmname
prevent element entry removal from directories by ordinary users
pre-rmbranch
prevent branch removal by ordinary users
pre-rmtype
prevent type (lbtype, brtype, etc.) removal by ordinary users
pre-rmelem
prevent element removal by ordinary users
pre-mkelem
prevent parallel creation of different files with the same name in the same directory
post-mkelem
modify the protections of newly created elements to give them the appropriate owner and group and read/write access permissions.
pre-mkbrtype
prevent branch-type creation by ordinary users
enforce branch-naming conventions
require comment on branch-creation
post-mkbrtype
attach branch-type attrs/hlinks on creation
pre-mklbtype
prevent label-type creation by ordinary users
enforce label-naming conventions
require comment on label-creation
post-mklbtype
attach label-type attrs/hlinks on creation
pre-mklabel
prevent labeling by ordinary users
pre-mktrtype
prevent trigger creation by ordinary users
pre-mkattype
limit attribute-type creation by ordinary users
pre-mkattr
limit attribute value assigment by ordinary users
post-mkattr
notification of attribute value changes
pre-submit (simulated)
simulate a pre-op trigger for completion/submission of a change-task as a single logical change-set.
post-submit (simulated)
simulate a post-op trigger for completion/submission of a change-task as a single logical change-set.
pre-mkview (simulated)
simulate a pre-op trigger for view creation
post-mkview (simulated)
simulate a post-op trigger for view creation
pre-rmview (simulated)
simulate a pre-op trigger for view removal
post-rmview (simulated)
simulate a post-op trigger for view removal
cmd-trigger (simulated)
simulate pre-op/post-op triggers for entire commands (rather than individual events)
Locks
task-lock
lock task branch against changes by non-owner
lock task branch/label type against changes after completed submission
integration/merge lock
lock integration lines against checkin by non-integrators
mainline lock
lock mainline against checkin by ordinary users
baselevel lock
lock baseline label definitions after baselining
floating label lock
lock floating labels against change by ordinary users
metadata lock
lock metadata (attributes and hyperlinks) against changes by ordinary users (unless performed automatically by triggers)
element lock
lock elements against modification by unauthorized users
component lock
lock "components" or "subsystems" against modification by unauthorized users
VOB lock
lock entire VOBs against access by unauthorized users
Multi-Site
Tool-Supported Roles/States
branch roles
branch states
component/subsystem roles
component/subsystem states
integration roles
integration states
build roles
build states
release roles
release states
administration roles
administration states
VOB Management
VOB naming conventions
Use of Admin VOBs
VOB per group
VOB per product
Multiple VOBs per product
VOBs shared by multiple products
VOBs shared by multiple groups
Separate VOB for documents
Separate VOB for externally supplied files
Separate VOB for tools and libraries
View Management
view naming conventions
users create their own views
tool creates user's views
users decide where to store their views
tool decides where to store user views
policies specifying viewstorage usage/locations
users can chmod/chgrp/chown their views
shared views (multiple developers in same view)
one developer per view
dedicated integration/build views
dedicated release views
view per task
view per developer
viewpool or upperbound on number of active views
view seeding
View seeding is a way of "pre-populating" a view with the needed derived object to speedup subsequent builds and winkins.
Config-Spec Management & Version Selection
users create their own initial cspecs
tool creates initial cspecs
users modify their own cspecs
tools modify user's cspecs
dynamic version selection
Some shops have developer's config-specs select the /LATEST versions on the codeline. As soon as they are checked in to the codeline, the developers may see them in their views. This can be more problematic if online development is permitted than if all work is done on task-branches.
static version selection
Some shops expressly do not select the /LATEST versions on the codeline. Instead, the select only the most recently labeled baselevel of the codeline.
static file versions but dynamic directories
Some shops will use static version selection for files, selecting the versions on a labeled baselevel, but use dynamic selection for directories (using a '-directory' rule to select the /LATEST versions on the codeline for directory elements). This lets developers always see the latest version of a directory in the codeline, and avoids collisions resulting from creating files by the same name on different branches. If a new file has been created by someone else, they will see the new file in their view, but not necessarily its contents.
selection of /main/0
Some groups (especially those that dont work directly on /main) will always insert a rule at the end of a config-spec that selects the /main/0 version of any file or directory not yet selected. This lets them see files and directories created in some other branch so they dont create colliding file or directory elements.
Version Management
of source code
of auto-generated source code
of derived object files
of built executables
of built libraries
of environment/options settings
of documents
of program data inputs/outputs
of test cases, test vectors, or test results
of build tools (compilers, linkers, debuggers)
of externally supplied libraries
of externally supplied and system header files
of externally supplied source code
of externally supplied binaries/images
Integration with Tracking System
on element creation
on version checkout
on version checkin
on uncheckout
on branch-type creation
on branch creation
on label-type creation
on label-creation
performer-verification
Verify that a particular ClearCase action (e.g., checkin/checkout or creation of a branch-type or label-type) is performed only by the user that is assigned or authorized to perform that action as declared in the corresponding change-request record.
on record state transitions
ClearCase data obtained from issue/task record
Target-Release defines Config-Spec
The target-release specified for a record in the tracking system is used to define or enforce the codeline and/or baseline (branch and/or label) used for development in the view's config-spec.
ClearCase data logged to issue/task record
Separate record-type for defects
Separate record-type for feature requests/development
Separate record-type for build/integration requests
Separate record-type for inspections/reviews
Separate record types for document changes
Document Management
Document naming conventions
Document ID naming conventions
Document location conventions
Concurrent Development for documents
Release Management
Release naming conventions
Release numbering conventions
Target-Release per Change/Feature
Every record for every change-request, bugfix, or feature/enhancement request is required to estimate an intended target release for the proposed change.
Integration approval per Request/Feature
Some shops require CCB approval before allowing integration of a requested feature, fix, or enhancement into a release-codeline. Approval is mode at the level of a given feature or function to decide not only if it should be integrated, but more importantly which release codeline/baseline it should be integrated into (possibly changing previous plans for the targeted baseline/release).
Integration approval per Change-Task
Some shops require CCB approval before allowing integration of any completed change-task into a release-codeline. Approval is mode at the level of a given task or subtask to decide not only if it should be integrated, but more importantly which release codeline/baseline it should be integrated into (possibly changing previous plans for the targeted baseline/release).
Access Control/Restrictions
Restrictive Code-Ownership
Subsystems and/or Modules of code are assigned a single owner responsible for their integrity, and no one but the code-owner is allowed to checkout (and/or checkin) a piece of code. This actually applies to other artifacts besides source-code, including documents and tests.
Relaxed Code-Ownership
Subsystems and/or Modules of code are assigned a single owner responsible for their integrity, and developers other than the code-owner are permitted to checkout (and/or checkin) a piece of code provided that they have permission from the code-owner. This actually applies to other artifacts besides source-code, including documents and tests.
Restrictive Codeline-Ownership
Individual Codelines are assigned to a single owner responsible for its integrity and no one but the codeline-owner is allowed to checkout from (and/or checkin to) the codeline.
Relaxed Codeline-Ownership
Individual Codelines are assigned to a single owner responsible for its integrity anddevelopers other than the codeline-owner are permitted to checkout from (and/or checkin to) the codeline provided that they have permission from the codeline-owner
Change Control Boards
CCB per component/team
Product-wide Software CCB
System-level CCB (includes both hardware and software)
Business-level CCB
Work approval per Request/Feature
Some shops require CCB approval for a request feature, fix, or enhancement before effort has been made to breakdown the proposed work into tasks and subtasks. Approval is mode at the level of a given feature or function. Subsequent approval of the constituent tasks needed to implement the functionality may or may not take place, and rejection of a task or subtask may change the current accept/reject status of the corresponding feature or fix.
Work approval per Change-Task
Many shops require a proposed change to obtain CCB approval before any development work can begin on that change. This is often done an a per-task basis, requiring approval for each planned development task (possibly including subtasks) for a given feature or request.
IBM/Rational Clearcase Client 6.0 Installation on Linux
This tutorial is for software developers using IBM/Rational Clearcase for change management (CM) on Linux. Unlike many of the text file based CM systems like RCS and CVS, Clearcase used its Multi Version File System (MVFS) to hold various revisions of a file and control locking of files checked out to a developer.
This tutorial covers the installation and configuration of Cleacase client (6.0) on Linux (Red Hat Enterprise Linux 4 [RHEL4] or 3 [RHEL3]) connecting to a Clearcase server. This tutorial covers the client installation only. IBM states that the Clearcase client is only supported on the Red Hat Linux or SuSE "Enterprise" distributions but the only thing limiting you to this distribution is the kernel version, files, directory structure and the version of gcc. The directory structure can be duplicated and the version of the kernel, C libraries and compiler can be matched to that used on Red Hat "Enterprise" or use a RHEL clone such as CentOS or WhiteBox. See details below.
Prerequisites:
* Check for installed packages: rpm -q gcc glibc-devel ncurses-devel
* Also requires RPM ncompress: rpm -ivh ncompress-X.X.X-XX.i386.rpm
This RPM contains the command uncompress required during installation.
* Linux Kernel source is required: Check to see if kernel source is installed:
Red Hat Enterprise 4 Red Hat Enterprise 3
Source instals with kernel RPM:
# ls /usr/src/kernels
2.6.9-34.EL-smp_i686
Source is included in a separate RPM:
# rpm -q kernel-source
kernel-source-2.4.18-14
Installs to: /usr/src/linux-2.4.21-32.EL/
The kernel source is required to build a new kernel module. We will be compiling a kernel module only and we will not be building or installing a new kernel. This step is required for building new kernel loadable modules (RHEL4: mvfs.ko and vnode.ko or RHEL3: mvfs.o and vnode.o) Clearcase ships with a pre-compiled kernel module for RHEL4.
* Snare kernels contain their source in the RPM package kernel-smp-devel-2.6.9-34_snare.EL (RHEL4)
* Clearcase server note: Note that the Clearcase server needs to be a Unix/Linux hosted Clearcase server. A Unix/Linux server can have Microsoft Windows clients as well as Unix and Linux clients. A Microsoft Windows server can not be used to host Unix or Linux clients.
DO NOT USE MICROSOFT WINDOWS AS A CLEARCASE SERVER!!!
Download Clearcase Client 6.0 (2003.06.00) for Linux:
* Download Red Hat Enterprise Linux client software: The versions are very specific. You will also have to be a licensed customer in order to perform the download.
o http://www.rational.com
o List of supported systems - platforms, OS and versions
o Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center" (requires a login and password)
o Download current full product versions: Select "V2003.06.00" + "Continue"
[Client download page]
o Download client software: C54UDNA.tar.Z
Select "Accept".
Note:
+ The download manager may ask for proxy settings, etc
+ This tar archive is good for installing Clearcase server and Clearcase client. It is the options chosen during installation and configuration which differentiate a server installation from a client installation.
* Download Latest IBM/Rational Clearcase Patch:
o http://www.rational.com
o Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center"
(requires a login and password)
o Select: "Available Patches and service releases"
o Enter in search box: "clearcase redhat" + Limit by type of support: "Downloadable files"
o Download patch: clearcase p2003.06.00-28 for (Red Hat: clearcase_p2003.06.00-28.rhat_x86.tar.gz)
o Download patch: clearcase p2003.06.00-29 for (Red Hat: clearcase_p2003.06.00-29.rhat_x86.tar.gz)
IBM/Rational use the following release numbers:
* Clearcase Version 6.0 Release number 2003.06 (This tutorial)
* Clearcase Version 5.0 Release number 2002.05 (Clearcase Client 5.0 on Red Hat 8.0 tutorial)
NFS mount Clearcase server:
For directories/mount points exported by the Clearcase server look at the NFS exports file /etc/exports (Solaris: /etc/dfs/dfstab).
Clearcase Client Configuration:
Typical Linux NFS client config file /etc/fstab:
(Solaris /etc/vfstab)
name-of-clearcase-server:/path-goes-here/vobstore /net/name-of-clearcase-server/vobstore nfs auto 0 0
name-of-clearcase-server:/path-goes-here/viewstore /net/name-of-clearcase-server/viewstore nfs auto 0 0
For use with separate mount points for views and VOBs.
Note: The mount point /vob is NOT an NFS mount. It is an internal Clearcase mount which will be generated by Clearcase.
or
name-of-clearcase-server:/net/cleardata /net/cleardata nfs auto 0 0
In this example we use a single mount point for views and VOBs where the cleardata directory contains the sub-directories clearcase_rls/, viewstore/ and vobstore/.
Another format, if one is using multiple VOB servers: /net/hostname/cleardata.
Clearcase Server Configuration:
Typical Clearcase NFS server (Linux) /etc/exports:
...
/opt/rational/clearcase_rls 192.168.0.0/16(rw insecure sync no_root_squash) - Used for install
/net/vobstore 192.168.0.0/16(rw insecure sync no_root_squash)
/net/viewstore 192.168.0.0/16(rw insecure sync no_root_squash)
...
The "no_root_squash" option allows root from other systems to have root privaleges on that filesystem. It fixes view deletion problems by root. The "no_root_squash" option can be assigned temporarily to fix problems when they occur.
Typical Solaris server /etc/dfs/dfstab:
...
share -F nfs /opt/rational/clearcase_rls
share -F nfs /net/vobstore -nohide
share -F nfs /net/viewstore -nohide
...
Mount NFS file systems:
After your /etc/fstab is configured properly you are ready to mount the Clearcase NFS server file system:
[client root prompt]# mount /net/name-of-clearcase-server/vobstore
[client root prompt]# mount /net/name-of-clearcase-server/viewstore
Installation of IBM/Rational Cleacase Client on Linux Red Hat Enterprise Linux:
As user root:
* Prepare directory structure:
o Create modules directory:
+ RHEL3: mkdir /lib/modules/fs
+ RHEL4: Creates directory for you /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs
o Create installation directory: mkdir /opt/rational/clearcase
o Create release directory: mkdir /opt/rational/clearcase_rls
o Files C54UDNA.tar.Z clearcase_p2003.06.00-28.rhat_x86.tar.gz and clearcase_p2003.06.00-29.rhat_x86.tar.gz are loaded to the release directory /opt/rational/clearcase_rls and the installation is performed from here (or the directory of your choice).
* Unpack basic client software:
o uncompress C54UDNA.tar.Z
o tar -xf C54UDNA.tar
This creates directory ./2003.06.00
(/opt/rational/clearcase_rls/2003.06.00)
* Unpack the patch:
o mv clearcase_p2003.06.00-28.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
o mv clearcase_p2003.06.00-29.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
o cd 2003.06.00/rhat_x86/clearcase/patches
o tar xzf clearcase_p2003.06.00-28.rhat_x86.tar.gz
o tar xzf clearcase_p2003.06.00-29.rhat_x86.tar.gz
* Apply patch to release area:
o cd clearcase_p2003.06.00-28/clearcase/install
o ./apply_patch
o cd ../../clearcase_p2003.06.00-29/clearcase/install
o ./apply_patch
Installation Log:
Site Preparation log:
[root prompt]# cd ../../../install
- Same as: /opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install
[root prompt]# ./site_prep
Updating release area '/opt/rational/clearcase/2003.06.00/rhat_x86'
For any of the queries that follow, help is available
by entering 'help', 'h' or '?' at the prompt.
Site default ClearCase license host: [Unknown] node-name-of-license-server
Site default ClearCase registry host: [Unknown] node-name-of-clearcase-server
Site default ClearCase registry data backup host: [Unknown]
Site default ClearCase registry region: [Unknown] devel - or the name you are using at your site.
Would you like to change the existing host data for setuid operation [no]
Would you like ClearCase Remote Administration to be enabled on clients [no]
[Potential Pitfall]: Turn off the NIS service "ypbind" if you get the following error:
ERROR: The albd_server is not correctly registered in the services
file of the Network Information database.
This results when the installation expects the services file to be fed by NIS and ignores the /etc/services file you edited and the added port albd/371.
Turn off ypbind: RHEL: service ypbind stop
Information for the previous entries can be obtained from an existing installation with the following Clearcase command: ct hostinfo -l
(/opt/rational/clearcase/bin/cleartool hostinfo -l)
The bold text indicates an entry. The rest were defaults chosen by the "Enter" key.
The "host", "license" and "region" are stored in the following configurations files:
* Host: /var/adm/rational/clearcase/rgy/rgy_hosts.conf
(Linked to /var/adm/atria/rgy/rgy_hosts.conf)
* Region: /var/adm/rational/clearcase/rgy/rgy_region.conf
* License server: /var/adm/rational/clearcase/config/license_host
The host and region are a single entry in their respective file. This file and the appropriate NFS mount points will be changed when connecting to a different VOB server.
Clearcase Client Installation log:
(/opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install/install_release)
[root prompt]# ./install_release
This release area contains the following Atria product(s):
MultiSite
ClearCase ClearQuest Integration
ClearCase Web Interface Server
ClearCase
ClearCase ClearDDTS Integration
A transcript of this installation will be initially written
to /tmp/Rational_install.XXXXXX.XX:XX.
After a successful installation, the transcript will be located
at /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX.
The following installation methods are available:
1. Local Install: Install occurs on the local host.
2. Remote Install: Install occurs on a single remote host.
3. Multiple Remote Installs: Install occurs on a set of remote hosts.
4. Local Deinstall: Deinstall occurs on the local host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit the installation
Please select the installation method by number.
Method of installation>> 1
- Type the letter "q" to get out of reading full text of agreement
Do you accept the terms of this license agreement? (y/n): y
- Type the letter "q" to get out of reading full text of agreement
Do you accept the terms of this license agreement? (y/n): y
The following installation operations or models are available:
1. Standard: Regular installation, allowing links to this release area.
2. Full-copy: Regular installation, with no links to this release area.
3. Mounted: Host install via mounted or pre-populated /opt/rational/clearcase or CLEARCASEHOME.
4. Link-only: Host install via a symbolic link to this release-area.
5. Deinstall: Deinstall software from the local installed host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit
Please select the installation type by number.
Model of installation>> 2
User specified:Install model:full
Specify directory in which Rational products are to be installed
[/opt/rational]:
Pathname to the network-wide release directory
(used as target of symbolic links)
[/opt/rational/clearcase_rls/2003.06.00/rhat_x86]:
1 : ClearCase Minimal Developer Installation - No GUI, import or integration tools
2 : ClearCase Server-only Installation - Needed for view or vob server. No docs, mvfs, client
3 : ClearCase MultiSite Full Function Installation
4 : ClearCase Web Interface Server
5 : ClearQuest Integration with ClearCase
6 : ClearDDTS Integration with ClearCase
7 : ClearCase Mainframe Connectors
8 : ClearCase MultiSite Shipping Server-only Installation
9 : ClearCase Full Function Installation - All features and functionality.
a : Select all
f : Finish selection
x : Toggle expanded descriptions
r : Reset selections
q : Quit
Selection number(s)>> 5
Selection number(s)>> 6
Selection number(s)>> 9
Next selection, '*' denotes a selected component
1 : ClearCase Minimal Developer Installation
2 : ClearCase Server-only Installation
3 : ClearCase MultiSite Full Function Installation
4 : ClearCase Web Interface Server
* 5 : ClearQuest Integration with ClearCase
* 6 : ClearDDTS Integration with ClearCase
7 : ClearCase Mainframe Connectors
8 : ClearCase MultiSite Shipping Server-only Installation
* 9 : ClearCase Full Function Installation
a : Select all
f : Finish selection
x : Toggle expanded descriptions
r : Reset selections
q : Quit
Selection number(s)>> f
ClearCase License Server Host[node-name-of-license-server]:
ClearCase Registry Server Host[node-name-of-clearcase-server]:
ClearCase Registry Backup Host(s)[Unknown]:
ClearCase Registry Region[devel]:
Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[no]:
Choose whether to install extended VOB support.
Install this feature? (yes, no, quit, help) [no]:
Continue installation?(yes, no, quit)[yes]:
Log file for this session: /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX
Comes with pre-compiled load modules for Red Hat Enterprise 4.
Using vnode module as released, copied to /lib/modules/2.6.9-34.EL/kernel/fs/mvfs.
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/vnode.ko
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/mvfs.ko
Red Hat Enterprise 3 will result in a request to build new modules:
This requires the presence of the RPM kernel-source.
Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[no]:
User specified:Rebuild vnode module: yes
Enter path to your toplevel kernel source directory.
Default is [/lib/modules/2.4.21-32.ELsmp/build]:
User specified:Linux source directory: /lib/modules/2.4.21-32.ELsmp/build
If you switch to a custom built kernel, then the Clearcase modules will not load and may not build. This problem is resolved in the next step.
This is also true if running the "Snare" kernel or a custom kernel for RHEL4.
Generate a new MVFS loadable modules:
Red Hat "Enterprise" Linux 4 kernels include kernel source and install to /usr/src/kernels/2.6.9-34.ELsmp_i686/
Red Hat "Enterprise" Linux 3 kernels require the installation of the separate kernel source RPM kernel-source, which installs to /usr/src/linux (linked to kernel source directory /usr/src/linux-2.4.XX).
If you change or modify your kernel or if the newly compiled modules from "install_release" produces "unresolved symbols" error, then perform the following:
Build new RHEL4 modules: (as root)
[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make clean
[root prompt]# make
Queries for kernel modules source path: /lib/modules/2.6.9-34.ELsmp/build
[root prompt]# make install
Build new RHEL3 modules:
(Compile kernel source but do not install.)
[root prompt]# cd /usr/src/linux-2.4.21-40
[root prompt]# make mrproper
[root prompt]# make oldconfig
[root prompt]# make dep
[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make
[root prompt]# make install
Creates loadable modules:
* RHEL4: (kernel 2.6)
o /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/mvfs.ko.
o /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/vnode.ko.
* RHEL3: (kernel 2.4)
o /lib/modules/fs/mvfs.o.
o /lib/modules/fs/vnode.o.
Also see: /var/adm/rational/clearcase/mvfs/vnode_src/README.txt
Start Clearcase client:
Create internal Clearcase mount points:
[root prompt]# service clearcase start
This start script (/etc/rc.d/init.d/clearcase) will create the directory /vob/... and generate internal mount points. This configuration is generated for you and will reside in the config file /etc/mtab. It will also perform a cleartool mount. The start script will also be executed during system boot. Once the service is started or the systems re-booted there is no need to re-execute this command manually.
The start script will load the kernel modules:
* insmod -f mvfs
* insmod -f vnode
* Performs a: cleartool mount -a
Check Clearcase vob and view mount points: df
To make sure the Clearcase service is started during system boot, see if it is turned on for init levels 3 and 5: chkconfig --list | grep clearcase
For more information, see the YoLinux init tutorial.
User configuration:
Unix permissions will permit and prevent users from editing files. Thus developers should permit others in their group to read and write files. Set this as a default by setting the umask in thier $HOME/.bahsrc file:
umask 002
or
umask 0002
Installing Clearcase with site_prep option "setuid_mounts" can change this behavior.
Clearcase uses .bashrc for it's clearcase "view" shell.
Append the following to your $HOME/.bashrc
if [ $CLEARCASE_ROOT ]
then
export PS1='[`basename $CLEARCASE_ROOT`]$PWD>'
fi
alias ct=cleartool
This will change your prompt whenever you are in a Clearcase "view" (shell). The "view" will be listed in the prompt adding sanity to your experience.
Append the following to your $HOME/.bash_profile
export PATH=/opt/rational/clearcase/bin:$PATH
export CLEARCASE=/opt/rational/clearcase
alias ct=cleartool
Either re-login or initialize your shell session with the new changes: . $HOME/.bash_profile
Test installation with the following commands:
* ct lsvob
* ct hostinfo -l
The user's uid (user id) as defined in /etc/passwd and the user's gid (group id) as defined in /etc/passwd and /etc/group MUST match that used on the Clearcase server otherwise file permissions may not be compatable on the Clearcase MVFS file system. Other users defined on the Clearcase server may have to be defined locally on the client system to resolve uid/gid references. (i.e. When the command ls -l is issued, it will list the user/group as defined by the gid/uid) This can be supported by added entries to the local /etc/passwd and /etc/group files, NIS or LDAP.
Check your uid/gid with the command "id"
The developer must create a view in order to use Clearcase:
cleartool mkview -tag user1_view -stgloc viewstore
Where "viewstore" is the view storage location name.
Find list of view storage locations: cleartool lsstgloc
Clearcase GUI xclearcase:
Gui tools loaded:
/opt/rational/clearcase/bin/xclearcase
xcleardiff
xlsvtree
Use the following shell script to launch xclearcase:
File: /opt/bin/startXclearcase
#!/bin/bash
# For older systems: export LANG=C
PATH=/opt/rational/clearcase/bin:$PATH
cd /vob
/opt/rational/clearcase/bin/cleartool setview -exec /opt/rational/clearcase/bin/xclearcase name_of_view &
Desktop launcher icon:
[Potential Pitfall]: For older releases of Linux (i.e. Red Hat 8.0 or 9.0), the environment variable LANG MUST be set to "C" or "en_US.iso885915". The default in Red Hat 8.0 and 9.0 is en_US.UTF-8 which will crash xclearcase.
To use a different editor other than the default "vi" set the editor environment variable.
Example: export EDITOR=emacs
Tip: To view the additional collumns of information select "File" + "Preferences..." + select the collumns to display.
This script is for a single user system as it specifies a given view. For a multiuser system use the command /opt/rational/clearcase/bin/xclearcase & which is not tied to a view but will allow the user to interactively select the view upon startup.
Licenses:
One can keep track of the number of client licenses used with the following Gnome desktop launcher.
File:
* Fedora/RHEL4: ~/Desktop/ClearcaseLicenses.desktop
* Old Red Hat 8/9: ~/.gnome-desktop/ClearcaseLicenses.desktop
[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Exec=/usr/X11R6/bin/xterm -bg black -fg green -s -hold -geometry x50 \
-title "Clearcase licenses currently used:" \
-e /opt/rational/clearcase/bin/clearlicense
TryExec=
Icon=/usr/share/pixmaps/gnome-gnomoku.png
X-GNOME-DocPath=
Terminal=false
Name[en_US]=Clearcase Licenses
GenericName[en_US]=
Comment[en_US]=
One may release a license with the command: clearcaselicense -release user-id
De-Install/Removal:
To remove Clearcase, remove the following:
/usr/rational/clearcase
/var/adm/rational/clearcase
/etc/rc.d/...clearcase
/opt/rational/clearcase_rls - or whatever directory you used.
/opt/rational/clearcase
/lib/modules/fs/mvfs.o (kernel 2.4) OR /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/* (kernel 2.6)
entries in: /etc/fstab
/etc/mtab
/vob
/view
Also the mount point to the VOB server would be deleted after unmounting the NFS file system.
Clearcase Client installation Distribution Dependancies:
The Red Hat Clearcase dependencies as shipped in its original form:
Red Hat Enterprise Linux 4 Red Hat Enterprise Linux 3
Kernel: 2.6.9-34 2.4.21-40
gcc: 3.4.5-2 3.2.3-52
glibc: 2.3.4-2.19 2.3.2-95.33
File: /etc/redhat-release:
* Red Hat Enterprise Linux Workstation 4:
Red Hat Enterprise Linux Server WS release 4 (Nahant)
* Red Hat Enterprise Linux Server 4:
Red Hat Enterprise Linux Server ES release 4 (Nahant)
* Red Hat Enterprise Linux Workstation 3:
Red Hat Enterprise Linux WS release 3 (Taroon Update 5)
* Red Hat 9.0:
Red Hat Linux release 9.0 (Shrike)
* Red Hat 8.0:
Red Hat Linux release 8.0 (Psyche)
Lock file path: /var/lock/subsys/
(File: /var/lock/subsys/clearcase)
Switching Clearcase Servers:
Script to switch to a new Clearcase server:
service clearcase stop
rm /var/adm/rational/clearcase/rgy/rgy_hosts.conf
echo "server_X" > /var/adm/rational/clearcase/rgy/rgy_hosts.conf
rm /var/adm/rational/clearcase/rgy/rgy_region.conf
echo "region_A" > /var/adm/rational/clearcase/rgy/rgy_region.conf
rm /var/adm/rational/clearcase/config/license_host
echo "license-server" > /var/adm/rational/clearcase/config/license_host
service clearcase start
Note the file system NFS mount should be in effect. It is not a problem to mount all the NFS servers at once. Only one can be an active Clearcase server at any given time. this script activates a single server. I have a script for each Clearcase server.
Clearcase Notes:
* Info:
o Clearcase Online Manuals and Documentation
o When Good VOBs Go Bad - IBM Web based training
o /usr/atria/doc/hlp/*.pdf - Installed
o /opt/rational/clearcase/2003.06.00/rhat_x86/doc/hlp/*.pdf - if client download is un-tarred to /opt/rational/clearcase.
o /opt/rational/clearcase/2003.06.00/rhat_x86/install/cdf/*.pdf
o /opt/rational/clearcase/doc/man/...
* A lower version of the Clearcase client will work with a higher version of the Clearcase view and VOB server or a matching version. The client can not have a higher version than the server.
* Clearcase uses port 371
* System tuning: One can set parameters in the startup script /opt/rational/clearcase/etc/clearcase_start
o For environments with a large number of users (client or server), increase the limit of files that lockmgr can handle. Default:
.../etc/lockmgr .... -f 256 ...
It is not unusual to increase this to 512.
* System tuning: MVFS scaling factors:
o mvfs_largeinit=(available RAM in GBytes)/2 + 1
Where mvfs_largeinit < 8.
You must reboot ccase after defining the mvfs_largeinit parameter.
o mvfs_vobfreemax=1800 Default =900
o mvfs_mnmax<=4096 Sets max number of objects. Grows dynamically if more required.
o mvfs_dncregmax: Number of files to cache.
o mvfs_dncdirmax: Number of directory names to cache.
* Only required if VOB/View is mounted non-NFS: Slocate will not index NFS mounted drives and thus Clearcase clients rarely have to change the slocate configuration. It is not desirable to have "slocate" index the view files. Disable this if necessary.
See the YoLinux Clearcase server slocate configuration.
* IBM/Rational:
o North America: 1-800-728-1212, 1-800-433-5444
Cupertino CA (408)863-4000
20 Maguire Road, Lexington MA 02421 (781)676-2460
o Europe/Middle East: 31-(0)20-4546-200 Netherlands
o Asia Pacific: 61-2-9419-0111 Australia
This tutorial covers the installation and configuration of Cleacase client (6.0) on Linux (Red Hat Enterprise Linux 4 [RHEL4] or 3 [RHEL3]) connecting to a Clearcase server. This tutorial covers the client installation only. IBM states that the Clearcase client is only supported on the Red Hat Linux or SuSE "Enterprise" distributions but the only thing limiting you to this distribution is the kernel version, files, directory structure and the version of gcc. The directory structure can be duplicated and the version of the kernel, C libraries and compiler can be matched to that used on Red Hat "Enterprise" or use a RHEL clone such as CentOS or WhiteBox. See details below.
Prerequisites:
* Check for installed packages: rpm -q gcc glibc-devel ncurses-devel
* Also requires RPM ncompress: rpm -ivh ncompress-X.X.X-XX.i386.rpm
This RPM contains the command uncompress required during installation.
* Linux Kernel source is required: Check to see if kernel source is installed:
Red Hat Enterprise 4 Red Hat Enterprise 3
Source instals with kernel RPM:
# ls /usr/src/kernels
2.6.9-34.EL-smp_i686
Source is included in a separate RPM:
# rpm -q kernel-source
kernel-source-2.4.18-14
Installs to: /usr/src/linux-2.4.21-32.EL/
The kernel source is required to build a new kernel module. We will be compiling a kernel module only and we will not be building or installing a new kernel. This step is required for building new kernel loadable modules (RHEL4: mvfs.ko and vnode.ko or RHEL3: mvfs.o and vnode.o) Clearcase ships with a pre-compiled kernel module for RHEL4.
* Snare kernels contain their source in the RPM package kernel-smp-devel-2.6.9-34_snare.EL (RHEL4)
* Clearcase server note: Note that the Clearcase server needs to be a Unix/Linux hosted Clearcase server. A Unix/Linux server can have Microsoft Windows clients as well as Unix and Linux clients. A Microsoft Windows server can not be used to host Unix or Linux clients.
DO NOT USE MICROSOFT WINDOWS AS A CLEARCASE SERVER!!!
Download Clearcase Client 6.0 (2003.06.00) for Linux:
* Download Red Hat Enterprise Linux client software: The versions are very specific. You will also have to be a licensed customer in order to perform the download.
o http://www.rational.com
o List of supported systems - platforms, OS and versions
o Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center" (requires a login and password)
o Download current full product versions: Select "V2003.06.00" + "Continue"
[Client download page]
o Download client software: C54UDNA.tar.Z
Select "Accept".
Note:
+ The download manager may ask for proxy settings, etc
+ This tar archive is good for installing Clearcase server and Clearcase client. It is the options chosen during installation and configuration which differentiate a server installation from a client installation.
* Download Latest IBM/Rational Clearcase Patch:
o http://www.rational.com
o Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center"
(requires a login and password)
o Select: "Available Patches and service releases"
o Enter in search box: "clearcase redhat" + Limit by type of support: "Downloadable files"
o Download patch: clearcase p2003.06.00-28 for (Red Hat: clearcase_p2003.06.00-28.rhat_x86.tar.gz)
o Download patch: clearcase p2003.06.00-29 for (Red Hat: clearcase_p2003.06.00-29.rhat_x86.tar.gz)
IBM/Rational use the following release numbers:
* Clearcase Version 6.0 Release number 2003.06 (This tutorial)
* Clearcase Version 5.0 Release number 2002.05 (Clearcase Client 5.0 on Red Hat 8.0 tutorial)
NFS mount Clearcase server:
For directories/mount points exported by the Clearcase server look at the NFS exports file /etc/exports (Solaris: /etc/dfs/dfstab).
Clearcase Client Configuration:
Typical Linux NFS client config file /etc/fstab:
(Solaris /etc/vfstab)
name-of-clearcase-server:/path-goes-here/vobstore /net/name-of-clearcase-server/vobstore nfs auto 0 0
name-of-clearcase-server:/path-goes-here/viewstore /net/name-of-clearcase-server/viewstore nfs auto 0 0
For use with separate mount points for views and VOBs.
Note: The mount point /vob is NOT an NFS mount. It is an internal Clearcase mount which will be generated by Clearcase.
or
name-of-clearcase-server:/net/cleardata /net/cleardata nfs auto 0 0
In this example we use a single mount point for views and VOBs where the cleardata directory contains the sub-directories clearcase_rls/, viewstore/ and vobstore/.
Another format, if one is using multiple VOB servers: /net/hostname/cleardata.
Clearcase Server Configuration:
Typical Clearcase NFS server (Linux) /etc/exports:
...
/opt/rational/clearcase_rls 192.168.0.0/16(rw insecure sync no_root_squash) - Used for install
/net/vobstore 192.168.0.0/16(rw insecure sync no_root_squash)
/net/viewstore 192.168.0.0/16(rw insecure sync no_root_squash)
...
The "no_root_squash" option allows root from other systems to have root privaleges on that filesystem. It fixes view deletion problems by root. The "no_root_squash" option can be assigned temporarily to fix problems when they occur.
Typical Solaris server /etc/dfs/dfstab:
...
share -F nfs /opt/rational/clearcase_rls
share -F nfs /net/vobstore -nohide
share -F nfs /net/viewstore -nohide
...
Mount NFS file systems:
After your /etc/fstab is configured properly you are ready to mount the Clearcase NFS server file system:
[client root prompt]# mount /net/name-of-clearcase-server/vobstore
[client root prompt]# mount /net/name-of-clearcase-server/viewstore
Installation of IBM/Rational Cleacase Client on Linux Red Hat Enterprise Linux:
As user root:
* Prepare directory structure:
o Create modules directory:
+ RHEL3: mkdir /lib/modules/fs
+ RHEL4: Creates directory for you /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs
o Create installation directory: mkdir /opt/rational/clearcase
o Create release directory: mkdir /opt/rational/clearcase_rls
o Files C54UDNA.tar.Z clearcase_p2003.06.00-28.rhat_x86.tar.gz and clearcase_p2003.06.00-29.rhat_x86.tar.gz are loaded to the release directory /opt/rational/clearcase_rls and the installation is performed from here (or the directory of your choice).
* Unpack basic client software:
o uncompress C54UDNA.tar.Z
o tar -xf C54UDNA.tar
This creates directory ./2003.06.00
(/opt/rational/clearcase_rls/2003.06.00)
* Unpack the patch:
o mv clearcase_p2003.06.00-28.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
o mv clearcase_p2003.06.00-29.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
o cd 2003.06.00/rhat_x86/clearcase/patches
o tar xzf clearcase_p2003.06.00-28.rhat_x86.tar.gz
o tar xzf clearcase_p2003.06.00-29.rhat_x86.tar.gz
* Apply patch to release area:
o cd clearcase_p2003.06.00-28/clearcase/install
o ./apply_patch
o cd ../../clearcase_p2003.06.00-29/clearcase/install
o ./apply_patch
Installation Log:
Site Preparation log:
[root prompt]# cd ../../../install
- Same as: /opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install
[root prompt]# ./site_prep
Updating release area '/opt/rational/clearcase/2003.06.00/rhat_x86'
For any of the queries that follow, help is available
by entering 'help', 'h' or '?' at the prompt.
Site default ClearCase license host: [Unknown] node-name-of-license-server
Site default ClearCase registry host: [Unknown] node-name-of-clearcase-server
Site default ClearCase registry data backup host: [Unknown]
Site default ClearCase registry region: [Unknown] devel - or the name you are using at your site.
Would you like to change the existing host data for setuid operation [no]
Would you like ClearCase Remote Administration to be enabled on clients [no]
[Potential Pitfall]: Turn off the NIS service "ypbind" if you get the following error:
ERROR: The albd_server is not correctly registered in the services
file of the Network Information database.
This results when the installation expects the services file to be fed by NIS and ignores the /etc/services file you edited and the added port albd/371.
Turn off ypbind: RHEL: service ypbind stop
Information for the previous entries can be obtained from an existing installation with the following Clearcase command: ct hostinfo -l
(/opt/rational/clearcase/bin/cleartool hostinfo -l)
The bold text indicates an entry. The rest were defaults chosen by the "Enter" key.
The "host", "license" and "region" are stored in the following configurations files:
* Host: /var/adm/rational/clearcase/rgy/rgy_hosts.conf
(Linked to /var/adm/atria/rgy/rgy_hosts.conf)
* Region: /var/adm/rational/clearcase/rgy/rgy_region.conf
* License server: /var/adm/rational/clearcase/config/license_host
The host and region are a single entry in their respective file. This file and the appropriate NFS mount points will be changed when connecting to a different VOB server.
Clearcase Client Installation log:
(/opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install/install_release)
[root prompt]# ./install_release
This release area contains the following Atria product(s):
MultiSite
ClearCase ClearQuest Integration
ClearCase Web Interface Server
ClearCase
ClearCase ClearDDTS Integration
A transcript of this installation will be initially written
to /tmp/Rational_install.XXXXXX.XX:XX.
After a successful installation, the transcript will be located
at /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX.
The following installation methods are available:
1. Local Install: Install occurs on the local host.
2. Remote Install: Install occurs on a single remote host.
3. Multiple Remote Installs: Install occurs on a set of remote hosts.
4. Local Deinstall: Deinstall occurs on the local host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit the installation
Please select the installation method by number.
Method of installation>> 1
- Type the letter "q" to get out of reading full text of agreement
Do you accept the terms of this license agreement? (y/n): y
- Type the letter "q" to get out of reading full text of agreement
Do you accept the terms of this license agreement? (y/n): y
The following installation operations or models are available:
1. Standard: Regular installation, allowing links to this release area.
2. Full-copy: Regular installation, with no links to this release area.
3. Mounted: Host install via mounted or pre-populated /opt/rational/clearcase or CLEARCASEHOME.
4. Link-only: Host install via a symbolic link to this release-area.
5. Deinstall: Deinstall software from the local installed host.
Type "Help" or "h" for expanded descriptions
Type "Quit" or "q" to exit
Please select the installation type by number.
Model of installation>> 2
User specified:Install model:full
Specify directory in which Rational products are to be installed
[/opt/rational]:
Pathname to the network-wide release directory
(used as target of symbolic links)
[/opt/rational/clearcase_rls/2003.06.00/rhat_x86]:
1 : ClearCase Minimal Developer Installation - No GUI, import or integration tools
2 : ClearCase Server-only Installation - Needed for view or vob server. No docs, mvfs, client
3 : ClearCase MultiSite Full Function Installation
4 : ClearCase Web Interface Server
5 : ClearQuest Integration with ClearCase
6 : ClearDDTS Integration with ClearCase
7 : ClearCase Mainframe Connectors
8 : ClearCase MultiSite Shipping Server-only Installation
9 : ClearCase Full Function Installation - All features and functionality.
a : Select all
f : Finish selection
x : Toggle expanded descriptions
r : Reset selections
q : Quit
Selection number(s)>> 5
Selection number(s)>> 6
Selection number(s)>> 9
Next selection, '*' denotes a selected component
1 : ClearCase Minimal Developer Installation
2 : ClearCase Server-only Installation
3 : ClearCase MultiSite Full Function Installation
4 : ClearCase Web Interface Server
* 5 : ClearQuest Integration with ClearCase
* 6 : ClearDDTS Integration with ClearCase
7 : ClearCase Mainframe Connectors
8 : ClearCase MultiSite Shipping Server-only Installation
* 9 : ClearCase Full Function Installation
a : Select all
f : Finish selection
x : Toggle expanded descriptions
r : Reset selections
q : Quit
Selection number(s)>> f
ClearCase License Server Host[node-name-of-license-server]:
ClearCase Registry Server Host[node-name-of-clearcase-server]:
ClearCase Registry Backup Host(s)[Unknown]:
ClearCase Registry Region[devel]:
Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[no]:
Choose whether to install extended VOB support.
Install this feature? (yes, no, quit, help) [no]:
Continue installation?(yes, no, quit)[yes]:
Log file for this session: /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX
Comes with pre-compiled load modules for Red Hat Enterprise 4.
Using vnode module as released, copied to /lib/modules/2.6.9-34.EL/kernel/fs/mvfs.
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/vnode.ko
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/mvfs.ko
Red Hat Enterprise 3 will result in a request to build new modules:
This requires the presence of the RPM kernel-source.
Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[no]:
User specified:Rebuild vnode module: yes
Enter path to your toplevel kernel source directory.
Default is [/lib/modules/2.4.21-32.ELsmp/build]:
User specified:Linux source directory: /lib/modules/2.4.21-32.ELsmp/build
If you switch to a custom built kernel, then the Clearcase modules will not load and may not build. This problem is resolved in the next step.
This is also true if running the "Snare" kernel or a custom kernel for RHEL4.
Generate a new MVFS loadable modules:
Red Hat "Enterprise" Linux 4 kernels include kernel source and install to /usr/src/kernels/2.6.9-34.ELsmp_i686/
Red Hat "Enterprise" Linux 3 kernels require the installation of the separate kernel source RPM kernel-source, which installs to /usr/src/linux (linked to kernel source directory /usr/src/linux-2.4.XX).
If you change or modify your kernel or if the newly compiled modules from "install_release" produces "unresolved symbols" error, then perform the following:
Build new RHEL4 modules: (as root)
[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make clean
[root prompt]# make
Queries for kernel modules source path: /lib/modules/2.6.9-34.ELsmp/build
[root prompt]# make install
Build new RHEL3 modules:
(Compile kernel source but do not install.)
[root prompt]# cd /usr/src/linux-2.4.21-40
[root prompt]# make mrproper
[root prompt]# make oldconfig
[root prompt]# make dep
[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make
[root prompt]# make install
Creates loadable modules:
* RHEL4: (kernel 2.6)
o /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/mvfs.ko.
o /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/vnode.ko.
* RHEL3: (kernel 2.4)
o /lib/modules/fs/mvfs.o.
o /lib/modules/fs/vnode.o.
Also see: /var/adm/rational/clearcase/mvfs/vnode_src/README.txt
Start Clearcase client:
Create internal Clearcase mount points:
[root prompt]# service clearcase start
This start script (/etc/rc.d/init.d/clearcase) will create the directory /vob/... and generate internal mount points. This configuration is generated for you and will reside in the config file /etc/mtab. It will also perform a cleartool mount. The start script will also be executed during system boot. Once the service is started or the systems re-booted there is no need to re-execute this command manually.
The start script will load the kernel modules:
* insmod -f mvfs
* insmod -f vnode
* Performs a: cleartool mount -a
Check Clearcase vob and view mount points: df
To make sure the Clearcase service is started during system boot, see if it is turned on for init levels 3 and 5: chkconfig --list | grep clearcase
For more information, see the YoLinux init tutorial.
User configuration:
Unix permissions will permit and prevent users from editing files. Thus developers should permit others in their group to read and write files. Set this as a default by setting the umask in thier $HOME/.bahsrc file:
umask 002
or
umask 0002
Installing Clearcase with site_prep option "setuid_mounts" can change this behavior.
Clearcase uses .bashrc for it's clearcase "view" shell.
Append the following to your $HOME/.bashrc
if [ $CLEARCASE_ROOT ]
then
export PS1='[`basename $CLEARCASE_ROOT`]$PWD>'
fi
alias ct=cleartool
This will change your prompt whenever you are in a Clearcase "view" (shell). The "view" will be listed in the prompt adding sanity to your experience.
Append the following to your $HOME/.bash_profile
export PATH=/opt/rational/clearcase/bin:$PATH
export CLEARCASE=/opt/rational/clearcase
alias ct=cleartool
Either re-login or initialize your shell session with the new changes: . $HOME/.bash_profile
Test installation with the following commands:
* ct lsvob
* ct hostinfo -l
The user's uid (user id) as defined in /etc/passwd and the user's gid (group id) as defined in /etc/passwd and /etc/group MUST match that used on the Clearcase server otherwise file permissions may not be compatable on the Clearcase MVFS file system. Other users defined on the Clearcase server may have to be defined locally on the client system to resolve uid/gid references. (i.e. When the command ls -l is issued, it will list the user/group as defined by the gid/uid) This can be supported by added entries to the local /etc/passwd and /etc/group files, NIS or LDAP.
Check your uid/gid with the command "id"
The developer must create a view in order to use Clearcase:
cleartool mkview -tag user1_view -stgloc viewstore
Where "viewstore" is the view storage location name.
Find list of view storage locations: cleartool lsstgloc
Clearcase GUI xclearcase:
Gui tools loaded:
/opt/rational/clearcase/bin/xclearcase
xcleardiff
xlsvtree
Use the following shell script to launch xclearcase:
File: /opt/bin/startXclearcase
#!/bin/bash
# For older systems: export LANG=C
PATH=/opt/rational/clearcase/bin:$PATH
cd /vob
/opt/rational/clearcase/bin/cleartool setview -exec /opt/rational/clearcase/bin/xclearcase name_of_view &
Desktop launcher icon:
[Potential Pitfall]: For older releases of Linux (i.e. Red Hat 8.0 or 9.0), the environment variable LANG MUST be set to "C" or "en_US.iso885915". The default in Red Hat 8.0 and 9.0 is en_US.UTF-8 which will crash xclearcase.
To use a different editor other than the default "vi" set the editor environment variable.
Example: export EDITOR=emacs
Tip: To view the additional collumns of information select "File" + "Preferences..." + select the collumns to display.
This script is for a single user system as it specifies a given view. For a multiuser system use the command /opt/rational/clearcase/bin/xclearcase & which is not tied to a view but will allow the user to interactively select the view upon startup.
Licenses:
One can keep track of the number of client licenses used with the following Gnome desktop launcher.
File:
* Fedora/RHEL4: ~/Desktop/ClearcaseLicenses.desktop
* Old Red Hat 8/9: ~/.gnome-desktop/ClearcaseLicenses.desktop
[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Exec=/usr/X11R6/bin/xterm -bg black -fg green -s -hold -geometry x50 \
-title "Clearcase licenses currently used:" \
-e /opt/rational/clearcase/bin/clearlicense
TryExec=
Icon=/usr/share/pixmaps/gnome-gnomoku.png
X-GNOME-DocPath=
Terminal=false
Name[en_US]=Clearcase Licenses
GenericName[en_US]=
Comment[en_US]=
One may release a license with the command: clearcaselicense -release user-id
De-Install/Removal:
To remove Clearcase, remove the following:
/usr/rational/clearcase
/var/adm/rational/clearcase
/etc/rc.d/...clearcase
/opt/rational/clearcase_rls - or whatever directory you used.
/opt/rational/clearcase
/lib/modules/fs/mvfs.o (kernel 2.4) OR /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/* (kernel 2.6)
entries in: /etc/fstab
/etc/mtab
/vob
/view
Also the mount point to the VOB server would be deleted after unmounting the NFS file system.
Clearcase Client installation Distribution Dependancies:
The Red Hat Clearcase dependencies as shipped in its original form:
Red Hat Enterprise Linux 4 Red Hat Enterprise Linux 3
Kernel: 2.6.9-34 2.4.21-40
gcc: 3.4.5-2 3.2.3-52
glibc: 2.3.4-2.19 2.3.2-95.33
File: /etc/redhat-release:
* Red Hat Enterprise Linux Workstation 4:
Red Hat Enterprise Linux Server WS release 4 (Nahant)
* Red Hat Enterprise Linux Server 4:
Red Hat Enterprise Linux Server ES release 4 (Nahant)
* Red Hat Enterprise Linux Workstation 3:
Red Hat Enterprise Linux WS release 3 (Taroon Update 5)
* Red Hat 9.0:
Red Hat Linux release 9.0 (Shrike)
* Red Hat 8.0:
Red Hat Linux release 8.0 (Psyche)
Lock file path: /var/lock/subsys/
(File: /var/lock/subsys/clearcase)
Switching Clearcase Servers:
Script to switch to a new Clearcase server:
service clearcase stop
rm /var/adm/rational/clearcase/rgy/rgy_hosts.conf
echo "server_X" > /var/adm/rational/clearcase/rgy/rgy_hosts.conf
rm /var/adm/rational/clearcase/rgy/rgy_region.conf
echo "region_A" > /var/adm/rational/clearcase/rgy/rgy_region.conf
rm /var/adm/rational/clearcase/config/license_host
echo "license-server" > /var/adm/rational/clearcase/config/license_host
service clearcase start
Note the file system NFS mount should be in effect. It is not a problem to mount all the NFS servers at once. Only one can be an active Clearcase server at any given time. this script activates a single server. I have a script for each Clearcase server.
Clearcase Notes:
* Info:
o Clearcase Online Manuals and Documentation
o When Good VOBs Go Bad - IBM Web based training
o /usr/atria/doc/hlp/*.pdf - Installed
o /opt/rational/clearcase/2003.06.00/rhat_x86/doc/hlp/*.pdf - if client download is un-tarred to /opt/rational/clearcase.
o /opt/rational/clearcase/2003.06.00/rhat_x86/install/cdf/*.pdf
o /opt/rational/clearcase/doc/man/...
* A lower version of the Clearcase client will work with a higher version of the Clearcase view and VOB server or a matching version. The client can not have a higher version than the server.
* Clearcase uses port 371
* System tuning: One can set parameters in the startup script /opt/rational/clearcase/etc/clearcase_start
o For environments with a large number of users (client or server), increase the limit of files that lockmgr can handle. Default:
.../etc/lockmgr .... -f 256 ...
It is not unusual to increase this to 512.
* System tuning: MVFS scaling factors:
o mvfs_largeinit=(available RAM in GBytes)/2 + 1
Where mvfs_largeinit < 8.
You must reboot ccase after defining the mvfs_largeinit parameter.
o mvfs_vobfreemax=1800 Default =900
o mvfs_mnmax<=4096 Sets max number of objects. Grows dynamically if more required.
o mvfs_dncregmax: Number of files to cache.
o mvfs_dncdirmax: Number of directory names to cache.
* Only required if VOB/View is mounted non-NFS: Slocate will not index NFS mounted drives and thus Clearcase clients rarely have to change the slocate configuration. It is not desirable to have "slocate" index the view files. Disable this if necessary.
See the YoLinux Clearcase server slocate configuration.
* IBM/Rational:
o North America: 1-800-728-1212, 1-800-433-5444
Cupertino CA (408)863-4000
20 Maguire Road, Lexington MA 02421 (781)676-2460
o Europe/Middle East: 31-(0)20-4546-200 Netherlands
o Asia Pacific: 61-2-9419-0111 Australia
Subscribe to:
Posts (Atom)
