Rational ClearCase provides a flexible set of tools that your organization uses to implement its development and change management policies. To use these tools, you need to understand the following concepts:
If your project uses the base ClearCase-ClearQuest integration, you need to understand the following concepts:
Read this chapter first. Then, if you want to start working immediately, use Help to learn as you go. Or, if you prefer a more structured approach, use the remainder of Working in Base ClearCase as a guide through the development cycle of your organization. The sections titled Under the Hood provide detailed information and suggest ways to become an advanced ClearCase user.
To start ClearCase Help, type the following command:
cleartool man contents
The help provides links to introductory material. To access the tutorials, type the following command:
cleartool man tutorials
For more information, see the discussion of online documentation in the Preface.
Items under ClearCase source control (version control) are generally referred to as elements. An element can be a design model, C++ source file, Visual Studio project, or a DLL. Elements are typically the objects on which you do work.
If your project uses the base ClearCase-ClearQuest integration, the things that you do in performing your work and their status are captured in activities. Activities are stored in ClearQuest user databases. Activities represent work assigned to you, and allow your project manager to gauge your progress.
This section describes the following concepts in understanding elements and activities:
To access files under ClearCase control, you set up and work in a view, which shows a directory tree of specific versions of source files.
ClearCase includes two kinds of views:
Each time you revise and check in a file or directory from a view, ClearCase creates a new version of it. Files and directories under ClearCase control (and all of their constituent versions) are called elements and are stored in VOBs. Figure 31 illustrates a VOB that contains the file elements prog.c, util.h, msg.cat, and lib.c.
Depending on the size and complexity of your software development environment, ClearCase elements may be distributed across more than one VOB. For example, the elements used by the documentation group are stored in one VOB, while the elements contributing to software builds are stored in a different VOB.
A set of rules called a configuration specification, or config spec, determines which files are in a view.
Config specs for snapshot views contain two kinds of rules: load rules and version-selection rules. Figure 32 illustrates how the rules in a config spec determine which files are in a view. In its examples, this manual describes views created by a user named Pat, who is working on release 1.4 of a product called Cropcircle. For purposes of clarity, Pat’s snapshot view names end in _sv.
Dynamic views use version-selection rules only (and ignore any load rules). A dynamic view selects all elements in all mounted VOBs, and then uses the version-selection rules to select a single version of each element. Instead of copying the version to your computer as a standard file, the view uses the MVFS (multiversion file system) to arrange the data selected in the VOB into a directory tree.
The rules in the config spec constitute a powerful and flexible language for determining which versions are in your view. For example, version-selection rules can specify the following criteria:
A label is a text annotation that you can attach to a specific version of an element. Usually, your project manager attaches a label to a set of versions that contributed to a specific build. A typical config spec rule uses version labels to select versions:
element * BASELINE_1
For example, if your project manager attaches version label BASELINE_1 to a version of element prog.c, any view configured with this rule selects the labeled version (unless some rule earlier in the config spec matches another version of prog.c). For more information about labels, see Managing Software Projects.
The version-selection rules are prioritized. For example, the view can try to select a version identified by a label first, and if no such version exists, the view can select a version based on a time rule.
In addition to affecting the way the element appears in views, labeling a version of an element also provides a way to access the version with a version-extended path (see The Version-Extended Path). Labeling a version effectively adds a new hard link to the version in the extended namespace. If you attach version label R4.1A to version /main/rls4/12 of element lib.c, these paths are equivalent:
In addition, a third path is usually equivalent:
This version-extended path is valid if it is unambiguous, that is, if no other version of lib.c is currently labeled R4.1A. (This is usually the case because, by default, label types are restricted to being used once per element. See the description of the –pbranch option in the mklbtype reference page in the Command Reference.)
Usually only one or two members of your software team learn the syntax for these rules and create config specs for everyone on the project to use. For more information, see Managing Software Projects and the config_spec reference page in the Command Reference.
In addition to versions of source files, a view also contains file-system objects that are not under ClearCase source control, such as temporary files that you create while developing your source files and other objects. These non-ClearCase file system objects are called view-private objects.
Your ClearCase administrator can integrate base ClearCase projects with a ClearQuest user database. You then associate versions of ClearCase elements on which you are working and change requests in a ClearQuest user database.
ClearQuest stores data in schema repositories and user databases. A schema defines the types of records in the user database and other attributes of the user database. ClearQuest stores all schemas in a schema repository. The ClearQuest user database stores your change-request data.
The base ClearCase schema package provides additional information in your ClearQuest records to track associations with ClearCase versioned objects. To support associations between base ClearCase versions and ClearQuest record types, the schema repository needs to have this schema package applied to selected record types. Then the target ClearQuest user database must be updated to add the new fields provided by the package.
Your ClearQuest user database may include different record types for different purposes. The record type used by the SAMPL ClearQuest user database supplied with the base ClearCase-ClearQuest integration is called a defect, but with the base ClearCase schema package installed, any change-request record type can be used.
The base ClearCase-ClearQuest integration consists of ClearCase triggers that fire when you check out an element, cancel a checkout, or check in an element. Your ClearCase administrator installs the integration triggers into each target VOB. The integration associates one or more change requests with one or more versions stored in one of the target VOBs.
The base ClearCase-ClearQuest integration provides either of the following:
The base ClearCase-ClearQuest integration has triggers on checkin, checkout, and cancel checkout operations. Working on versions, you can do the following:
Using the ClearQuest user database, you can do the following:
ClearCase administrators can do the following:
A ClearCase administrator adds the base ClearCase schema package to a schema and applies the change to one or more change-request record types. The policy that the administrator sets for one or more VOBs specifies the conditions under which you are prompted to associate versions with change requests.
The combination of config spec rules, views, VOBs, and branches (described in Working On a Team) provide the basis for parallel development, a strategy in which an organization can work on multiple versions of the same source file concurrently. For example, you are working on release 1.4 of a software product, and you want to experiment with the graphic user interface as a result of feedback from usability testing. You can create a view that isolates your modifications from the rest of the release 1.4 development project. Although you work with the same set of files used in the official builds, the versions of the files that you create from this view evolve separately from the versions used in the official builds. When you are satisfied with your usability modifications, you can use ClearCase tools to merge your work with the files used in the official release 1.4 build.
A version tree for an element has the same form as a standard directory tree (see Figure 33), which compares components of the version tree to components of a directory tree in extended namespace.
As a component of the version tree, the element is the root of the directory tree in the extended namespace. The element itself appears to be a directory, which contains a single subdirectory, corresponding to the main branch. (It can also contain some version labels.)
A branch in the version tree appears as a subdirectory in the extended namespace. As a directory, each branch can contain files (individual versions and version labels), directories (subbranches), and links (version labels).
A version in the version tree is a leaf name of the directory tree in the extended namespace. Each version of an element is a leaf of the directory tree. For a file element, the leaf contains text lines or binary data. For a directory element, the leaf contains a directory structure.
Accordingly, any location within the version tree of an element can be identified by a path in this extended namespace: