Go to a directory that affords you some privacy. The tutorial will create ClearCase data structures below this directory; accordingly, it must:

The “preferred” location is your home directory. But you may need to select another location—for example, if your home directory is located on a ce%ntral file server host, where ClearCase is not installed.

% cd $HOME

or, possibly

% mkdir /usr/tmp/USER ; cd /usr/tmp/USER

^[1] If you select a location outside your home directory, be sure to “personalize” it, as discussed on page 2.

---

Note: On some systems (DEC Alpha, for example), files in /tmp and /usr/tmp are routinely deleted, at reboot time and/or by periodic cron jobs. Some systems (Solaris 2.x, for example), configure /tmp as swap space, which will cause Step 5 to fail later in this lesson. Check with your system administrator before using /tmp or /usr/tmp as a storage location.

---

To verify that you'll be able to work through the tutorial successfully, run this script:

% /usr/atria/doc/tutorial/CHECK

The CHECK script verifies that:

If any of these requirements is not satisfied, the CHECK script displays a message explaining how to remedy the situation. For more information on these issues, read the comments in the CHECK script itself.

Create a subdirectory—assumed hereafter to be named tut—then go to that subdirectory. All ClearCase data structures created during this tutorial (except for file system mount points) will be stored in the tut subdirectory.

% mkdir tut
% cd tut

With ClearCase, a project's permanent and/or shared data storage is organized into versioned object bases (VOBs). Most real-life projects use a collection of related VOBs, but for this tutorial, a single VOB will suffice.

A VOB is implemented as a directory hierarchy, whose top-level directory is termed the VOB storage directory. The principal components of a VOB storage directory are:

These data structures are managed automatically by ClearCase server programs. On a day-to-day basis, you don't even have to know where a VOB storage directory is located. Instead, you access the VOB through its VOB-tag, which specifies the VOB's logical location on your host.

On UNIX systems, a VOB-tag is actually a mount point, because each a VOB is mounted and accessed as a separate file system. (A typical UNIX mount makes an entire disk partition accessible; a type-MVFS mount provides access to the directory structure created by a mkvob command.) Once a VOB is activated (mounted), you can access it using ClearCase programs and standard UNIX programs.

Figure 1-2. Mounted VOB

Let's create your tutorial VOB now. The mkvob command, which creates a VOB, also requires that you specify its VOB-tag. We suggest that you mount the VOB in directory /tmp, and that you use this “formula” to devise a VOB-tag:

VOB-tag = /tmp/USER_HOST_hw

(The “hw” stands for “Hello, world”.) It is important to personalize and localize the VOB-tag—other users may run the tutorial on the same host, and you may have occasion to run the tutorial on another host.

Throughout this manual, we refer to the location where you've mounted the VOB using the symbol VOBTAG.

% cleartool mkvob -tag VOBTAG -c "tutorial VOB" tut.vbs
Created versioned object base.
Host-local path: HOST:HOME/tut/tut.vbs
Global path:     VOBTAG
VOB ownership:
  owner USER
  group GROUP
Additional groups:
 ...

% mkdir VOBTAG
% cleartool mount VOBTAG

(The VOBTAG “mount-over” directory may already exist. If so, mkdir issues a harmless error message.) The ClearCase mount command makes the VOB accessible to user-level software at the pathname specified by VOBTAG.

---

Note: If your VOB-tag directory gets deleted (for example, you put it in /tmp and a cron job deletes it) don't worry; the VOB is safe. Simply repeat this step to reactivate it.

---

Your new, empty VOB is now ready to use. Our plan was to join the project after its second release, so run a script to create the first two releases. You must specify the VOB-tag as a command-line argument.

% /usr/atria/doc/tutorial/REL1REL2 VOBTAG
 .
 .
 .
*****************************************************
*                                                   *
*   Releases "REL1" and "REL2" have been created.   *
*    You are now ready to create another release,   *
*                to be called "REL3".               *
*                                                   *
*****************************************************

The VOB now contains a considerable amount of development data:

The VOB stores all the versions of all these files (and, as you'll see in this tutorial, a good deal of other information, too).

Let's try to see what all that data looks like.

% cd VOBTAG
% ls -l

Nothing appears because, in some sense, a VOB contains too much data. It is only on rare occasions that you want to see all of a file's historical versions. So instead of showing you a potentially confusing glut of data, ClearCase blocks out the data completely.

Most of the time, you wish to see just one version of each of a VOB's files. (Often, it's the most recent version, but sometimes not.) Together, a consistent, matched set of versions constitute a particular configuration of the source tree. ClearCase includes a powerful and flexible tool for defining, viewing, and working with configurations—the view. In essence, a view makes any VOB appear to be a standard directory tree, by selecting one version of each version-controlled object.

Figure 1-3. ClearCase view

A view also has some of the characteristics of a “sandbox,” common in home-grown development environments. Most importantly, it provides isolation: developers working in different views can modify files (perhaps even the same files) and rebuild software, without disturbing others' work.

It's often useful to think of the view as being above the file system instead of within it, an omnipresent lens through which you can see all the data on your host—in particular, all mounted VOBs.

The REL1REL2 script you ran in Step 7 created a view, which it used to create and modify source files, and to build the first two releases of the hello project. Now, create your own view, in which you'll continue project development.

Syntactically, creating a view is much like creating a VOB: you specify a view storage directory (the view's “real” location), along with a view-tag (the view's logical location). On a day-to-day basis, you reference a view using its view-tag—you can safely forget about the view storage directory itself.

A view-tag takes the form of a simple directory name; use this formula to devise a tag for this view:

view-tag = USER_HOST_tut

For example, if you are user “eve” working on host “venus”, you would use view-tag eve_venus_tut. (Be sure to personalize all the ClearCase view-tags you create—each view-tag you create is globally visible!)

% cd HOME/tut
% cleartool mkview -tag USER_HOST_tut tut.vws
Created view.
Host-local path: HOST:HOME/tut/tut.vws
Global path:     /net/HOST/HOME/tut/tut.vws

Once you have created a view, you can use it in several ways. The simplest way is to create a shell process that accesses all of your host's data through that view. Such a process is said to be set to the view.

% cleartool pwv -short
** NONE **
% echo $$
3409
% cleartool setview USER_HOST_tut
% cleartool pwv -short
USER_HOST_tut
% echo $$
3506

The pwv (“print working view”) commands before and after the setview command show that the new shell is, indeed, set to the view named USER_HOST_tut. The echo commands display the process number of the current shell, showing that a new shell process has been created.

Now, let's get acquainted with the hello project.

Development environments based on “sandboxes” force you to practice double-think—where you work (your sandbox) differs from where the sources are “really” stored (perhaps an SCCS or RCS source tree). With ClearCase, there is no such artificial distinction. Once you set a view, you work directly with the “real” source tree. For the most part, you can forget that you are using a special mechanism (the view) to access the data. We use the term transparency to describe this property of views.

To summarize, you simply set your view context with a setview command, and then work directly with your data—“set it and forget it.”

Your VOB is mounted at VOBTAG. Let's go there.

% cd VOBTAG

The REL1REL2 script created this directory structure (Discussion of a VOB's lost+found directory is beyond the scope of this manual.):

VOBTAG
	/src
	/bin

The src directory stores the hello project's source files; the bin directory stores the project's binaries, as they are to be released to customers. (Actually, each release consists of just one binary file, named hello.) All the files are all version-controlled in exactly the same way—ClearCase can handle any kind of file. (This capability makes it preferable to characterize a VOB as a “development tree”, rather than a “source tree”.) Let's see what the VOB's source directory contains.

% cd src
% ls -l
total 4
-r--r--r--   1 USER      GROUP     134 May 20 15:40 Makefile
-r--r--r--   1 USER      GROUP     196 May 20 15:41 hello.c
-r--r--r--   1 USER      GROUP     140 May 20 14:46 hello.h
-r--r--r--   1 USER      GROUP     223 May 20 17:05 util.c

As far as standard UNIX ls(1) is concerned (along with vi(1), cat(1), cp(1), and all other standard UNIX programs), this is simply a directory containing some sources files and a makefile. Note that the files are all read-only.

Each of the files listed above is a file element, with a hierarchical version tree. All of the versions of each file element are stored in the VOB; but just one version is visible through the “lens” of your view. The ClearCase variant of the ls command shows exactly which version appears.

% cleartool ls -short

Makefile@@/main/2
hello.c@@/main/3
hello.h@@/main/1
util.c@@/main/1

(Directories in a VOB are elements, too, with version trees of their own. We'll wait until Lesson 4 to work with this ClearCase feature.)

For example, hello.c@@/main/3 indicates that for file element hello.c, your view selects version 3 on the main branch.

Why does your view select these particular versions? Because they are the newest ones in their respective version trees. We will explore version-selection by views and user-defined configurations in Lesson 4.

Although your view selects just one version of an element, you can list the entire version tree.

% cleartool lsvtree -all hello.c

hello.c@@/main
hello.c@@/main/0
hello.c@@/main/1
hello.c@@/main/2        (REL1)
hello.c@@/main/3        (REL2)

This version tree is very simple: a single “main” branch contains a few versions, with no subbranches. Version 2 has been assigned a version label, “REL1”; version 3 has been labeled “REL2”. Version labels play an important role in ClearCase. They provide mnemonic access to versions—it's easier to remember the label “REL2” than it is to remember “version 3 went into the second release.” More important, when applied throughout a development tree, a single label can define a collection of versions—for example, version 2 of Makefile, version 3 of hello.c, version 1 of hello.h, and version 1 of util.c.

The use of slash ( / ) characters in the lsvtree listing suggests that an element's version tree is analogous to a directory tree. In fact, the structures are identical. The version tree for hello.c does not make a particularly interesting picture at this point, so compare the ways in which a fictional element with many subbranches can be pictured:

Figure 1-4. Example Version Trees

In the “directory tree” format, each “directory” (represented by a rectangle) is a branch; each “file” (circle) is actually a version.

ClearCase exploits the fact that a version tree is structurally identical to a directory tree. It extends the UNIX file system, allowing you to access any version of an element directly, using a version-extended pathname. For example, you can access version 2 of hello.c, even though your view selects version 3. Extended pathnames work with any UNIX command—for example, cat(1) and diff(1).

% cat hello.c@@/main/2
  int main() {
    printf("Hello, world!\n");
    return 0;
  }
% diff hello.c@@/main/2 hello.c
0a1,2
> #include "hello.h"
> 
2c4,6
<     printf("Hello, world!\n");
---
>     printf("Hello, %s!\n", env_user() );
>     printf("Your home directory is %s.\n", env_home() );
>     printf("It is now %s.\n", env_time() );
4a9

The @@ (extended naming symbol) in a version-extended pathname distinguishes the individual version of an element selected by a view from the entire element. In this step:

In effect, an extended name overrides the view's version-selection mechanism. ClearCase often includes the extended naming symbol in its output for consistency, and to facilitate cut-and-paste operations.

You have examined an “old” version of a source file in the src directory. You can also run “old” versions of the executable, hello, in the bin directory.

% cd ../bin
% hello@@/main/1
Hello, world!
% hello@@/main/2
Hello, USER!
Your home directory is /net/HOST/home/USER.
It is now DATESTRING
.

As in Step 16, a version-extended pathname accesses a particular version of an element. In this case, the versions are executables, not sources. The REL1REL2 script checked in the “first release” build of hello as version 1 of element VOBTAG/bin/hello. Similarly, it checked in the “second release” build of hello as version 2 of the same element.