This chapter describes how to set up a new ClearCase view for a development project.
 | Note: Your organization may have policies or restrictions as to where you can create a view. For example, you might be required to use a particular disk that is part of a strictly-observed data-backup scheme. And in some organizations, individual users are not permitted to create their own views. Consult with your system administrator before actually creating any views. |
Before creating a view, consider how, and by whom, it will be used:
Should other users be able to read data in your view (perhaps the contents of a source file that you have checked out and edited)?
Should other users be able to write data in your view (perhaps you will occasionally share the view with another user)?
Will the view be used principally, or exclusively with a particular VOB or a small, localized set of VOBs?
Will the view be used to export one or more VOBs to non-ClearCase hosts?
Keep in mind that others users working on the same project do not necessarily need to explicitly access your view in order to share your work. When you build software with clearmake, the resulting derived objects are automatically sharable. On the source level, a typical strategy is to have each project member use a separate, personal view; but all these views are configured with the same config spec. With this strategy, each user's changes to checked-out source files and directories will be visible only to that user. When the user checks in a version, the changes become visible to all other group members — all those using like-configured views.
Your umask(1) setting at the time you create a view affects how accessible it will be to others. For example:
A umask of 002 is appropriate for a view that you will share with other users in the same group. Members of your group will be able to create and modify view-private data; those outside your group will be able to read view-private data, but won't be able to modify it. To completely exclude non-group members, set your umask to 007.
A umask of 022 will produce a view in which only you can write data, but anyone can read data.
A umask of 077 is appropriate for a completely private view. No other user will be able to read or write view-private data.
Change your umask in the standard way. For example:
% umask 022 |
A view is implemented as a view storage directory, with an associated view_server process. Accordingly, ClearCase imposes these requirements on view creation:
A typical location for a view is your home directory. At some sites, however, a user's home directory may fail to meet the second requirement — it may be located on a file-server host where ClearCase is not installed.
If the view will be used to access a particular VOB, placing the view on the same host as the VOB may provide a significant reduction in network traffic. In general, we don't advise placing additional loads on a VOB server host; so save this technique for special cases — for example, a shared view used for a final-integration-and-test task. Non-ClearCase access is a special case in which you should create a view on the same host as a VOB — see “Setting Up an Export View for Non-ClearCase Access,” in the CASEVision™/ClearCase Administrator's Manual.
If you will be using the view on several hosts, make sure that the location at which you create the view can be accessed by all those hosts. For example, you use a view on several hosts at the same time when performing a distributed build. See Chapter 13, “Setting Up a Distributed Build.”
In selecting new view's view-tag, take into account the fact that it will be a unique, network-wide identifier for the view.[1] Thus, names like myview, work, or tmpvu are to be discouraged. You, and perhaps other users, may often need to type the view-tag in view-extended pathnames — for example, /view/view-tag/vobs/proj. Thus, try not to select a name that is too long or too hard to type correctly. Following are some suggested names:
| josef | personal view | |
| akp_home | personal view, located in your home directory | |
| akp_neptune | personal view, located on remote host neptune | |
| RLS1.2_fix | shared view for use in a particular bugfixing task | |
| monet_exp | view to be used to export a VOB named monet |
In any case, keep in mind the restriction that a view-tag must take the form of a simple directory name.
Having adjusted your umask (if necessary), selected a location for the view storage directory, and selected a view-tag, you are ready to create the view.
In xclearcase, bring up the View Browser, which displays information on all existing views. Then, select the Create menu choice.
Here's how to use cleartool to create the same view as in the preceding section:
% cleartool mkview -tag gomez ~/views/gomez.vws Created view. Host-local path: einstein:/home/gomez/views/gomez.vws Global path: /net/einstein/home/gomez/views/gomez.vws It has the following rights: User : gomez : rwx Group: dvt : rwx Other: : r-x |
When you create a view, ClearCase stores information regarding its location in the network-wide view storage registry. It derives this information heuristically; in some networks, you must update this information to guarantee global accessibility of your new view.
As the example above shows, mkview displays its “guess” as to a globally-valid pathname to the view storage directory:
... Global path: /net/einstein/home/gomez/views/gomez.vws ... |
If this pathname is not valid on all hosts in the network, you may be able to use the register command to substitute a globally-valid pathname in the storage registry entry. This topic is discussed in Chapter 3, “Using the ClearCase Graphical User Interface,” and Chapter 7, “Setting Up ClearCase Views,” , in the CASEVision™/ClearCase Administrator's Manual.
Before you start using your new view, you may need to revise its config spec, in order to select a particular configuration of source versions. Every view is created with the default config spec:
element * CHECKEDOUT element * /main/LATEST |
In many organizations, new development takes place on the main branch, while special projects take place on subbranches. The default config spec is appropriate for new development work in such a situation.
There are several ways to reconfigure a view with a non-default config spec:
Copy a project-specific file — Your ClearCase administrator may publish the pathname of a file containing the correct config spec for your project. Use the setcs command to reconfigure your view; then use catcs to confirm the change. For example:
% cleartool setview gomez % cleartool setcs /usr/local/lib/munchkin_proj % cleartool catcs . . <new config spec displayed> .
If the administrator subsequently revises the contents of that file, you'll need to enter the same setcs command again to update your view's configuration.
If the administrator subsequently revises the contents of that file, you can update your view's configuration by having the view_server reinterpret its current config spec:
% cleartool setcs -current |
Compose your own config spec — There is no single method for composing a set of rules that go into a config spec. The language described in the config_spec manual page has many features, and can be used to create many “special effects”. Having stated that proviso, we present below a step-by-step procedure for writing a config spec that uses the standard ClearCase baselevel-plus-changes model. Be sure also to consult:
Chapter 5, “Defining View Configurations,” which presents and explains a collection of config specs.
Chapter 6, “Working in a Parallel Development Environment,”, which examines in more detail the creation of the “standard” config spec for a project that is to “work on a branch”.
A few simple questions are presented below, based on the assumption that your development proceeds according to a baselevel-plus-changes model. In a well-managed environment, the answers to the questions will be simple, too, and writing the correct config spec will be easy.
Describe the set of versions that make up the baselevel that constitutes the project's starting point. Typical answers are:
“all the versions that went into Release 1.3”
“the versions of source files that went into Release 1.3, but use the Release 1.2 version of the libsort library”
“all the versions that went into last night's build of the sortmerge executable”
If the answer is “the most recent versions on the main branch”, then you should probably just use the default config spec. We'll assume that you wish to work with a “more interesting” set of versions.
Often, the translation from English-language description to ClearCase meta-data is very simple: “the versions that went into Release 1.3 are all labeled RLS1.3” corresponds to this config spec rule:
element * RLS1.3 |
Similarly, “the versions that went into last night's sortmerge build are listed in its config spec” might correspond to:
element * -config sortmerge@@11-Mar.09:07.1559 |
Sometimes, the description is a bit more involved. It may help to think of simple sets of versions as being “layers” in a more complex configuration (See Figure 4-1).
In this example, the RLS1.2 rule should precede the RLS1.3 rule, because the Release 1.2 versions of the libsort sources are to be selected in preference to (that is, are to be “layered on top of”) the Release 1.3 versions.
For most projects, the answer is “yes”, in which case the config spec should begin with the standard CHECKEDOUT rule:
element * CHECKEDOUT |
Some projects may not modify any sources — for example, a performance-testing or QA project.
Devise a new branch name that describes your project. Often, the branch name is related to a version label that defines the baselevel. For example, a rls1.3_fix branch might be used to modify a baselevel defined with RLS1.3 labels.
The config spec should include a rule that selects the most recent version on the branch:
element * .../rls1.3_fix/LATEST |
Note the use of ellipsis (“...”), which allows the branch to be located anywhere within an element's version tree, not just as a subbranch of the main branch. This rule should precede the rule(s) that define the project's baselevel — versions created during the project are to be preferred to versions in the underlying baselevel.
At some point before beginning work on the project, you (or an administrator) must create a branch type with the chosen name. Be sure to enter a meaningful comment:
% cleartool mkbrtype rls1.3_fix Comments for "rls1.3_fix": Branch for project fixing bugs in Release 1.3 (version label RLS1.3) . Created branch type "rls1.3_fix". |
| Note: Label types and branch types share a single namespace. Observe the convention of spelling names of label types with capital letters, and names of branch types with lowercase letters. |
We encourage you to answer “yes”. Using the view to “work on a branch” is much simpler if you let the view do the branching. When you wish to modify any element, you simply use checkout; if no project-specific branch has been created at the baselevel version yet, a mkbranch (“make branch”) command is executed automatically.
Here's how you would modify the rules in Figure 2-1 that define the baselevel, in order to turn on this auto-make-branch capability:
element libsort/*.[ch] RLS1.2 -mkbranch rls1.3_fix element * RLS1.3 -mkbranch rls1.3_fix |
If you've defined your baselevel by referencing one or more derived objects, you cannot use a -mkbranch clause; you must create branches explicitly, using mkbranch.
If so, include this rule from the default config spec as the final rule in your config spec:
element * /main/LATEST |
We suggest that you include this rule in the auto-make-branch scheme, too:
element * /main/LATEST -mkbranch rls1.3_fix |
With this rule, creating a new element will:
create a main branch, along with version 0 on the branch
create subbranch rls1.3_fix at version /main/0, along with version /main/rls1.3_fix/0
checkout version /main/rls1.3_fix/0
If you will not be creating any new versions, your view may not need to select main branch versions of any elements. As a convenience, however, you may wish to include the standard /main/LATEST rule, to enable the view to access data belonging to other projects, located in other VOBs.
Having devised your own config spec (on paper), configure your view with it:
% cleartool edcs -tag gomez . . <use text editor to revise default config spec — for example,> element * CHECKEDOUT element * .../rls1.3_fix/LATEST element libsort/*.[ch] RLS1.2 -mkbranch rls1.3_fix element * RLS1.3 -mkbranch rls1.3_fix element * /main/LATEST -mkbranch rls1.3_fix |
Now that your view is configured, you can start using it. (Actually, you can reconfigure a view at any time — before or after you start using it.) This is termed establishing a view context — a set view or a working directory view.
Typically, most of your work involves just one view. Moreover, you will probably want to use standard operating system pathnames to access version-controlled objects. For both these reasons, you will probably want to begin your ClearCase work by setting a view. This creates a process in which an element's standard name automatically accesses a particular version of that element — the version selected by the view's config spec, as discussed above.
This set view capability completes ClearCase's transparency feature — the version-control mechanism disappears completely, allowing system software and third-party applications to process versions of elements as if they were ordinary files, using ordinary pathnames.
A process with a set view can spawn any number of subprocesses, to any nesting level, using standard UNIX commands and subject to standard UNIX restrictions. All these subprocesses are also set to the view.
Transparency also applies to derived objects, in a slightly different manner. The standard name of a DO can reference different files in different views. But a DO appears in a view by virtue of having been built there by clearmake, not through the config spec facility.
Select View -> Set, which brings up the View Browser. Then, select a view from this browser.
When you are set to a particular view, you may still occasionally wish to access other views. For example, if you are set to view gamma, you can compare your version of util.c with the one selected by view alpha. Following are two ways to accomplish this.
While in a set view, use a view-extended pathname to “reach into” another view. See Figure 4-2.
“Temporarily” go to another view, then “reach back” to the set view. See Figure 4-3.
In the second method, you change your current working directory (CWD) to another view — that is, to a “remote” location in ClearCase's view-extended namespace. See Figure 1-6. This is termed “changing your working directory view”, and is reported by the pwv command like this:
% cleartool pwv Working directory view: alpha Set view: gamma |
There may be some situations in which you find it necessary (or simply prefer) to use working directory view contexts, dispensing with the set view facility. For example, processes started by init(1M) at system startup time cannot be set to a view. Such a process can process VOB data only by referencing files with view-extended pathnames and/or by setting its current working directory to a view-extended pathname.
If you routinely work with several views, you may find it easier to keep yourself organized by explicitly specifying the view context in which each pathname is to be interpreted.
The following commands illustrate this mode of usage:
% cd (go to home directory) % cleartool pwv (no view context) Working directory view: ** NONE ** Set view: ** NONE ** (full pathname has no view context,) % ls /usr/hw/src/util.c (and so cannot access VOB data) ls: /usr/hw/src/util.c: No such file or directory % cd /view/akp/usr/hw/src (go to view-extended pathname) % cleartool pwv (you now have a) Working directory view: jj (working directory view context) Set view: ** NONE ** % ls util.c (relative pathname works, because it uses) util.c (your working directory view context) |
| Note: The standard full pathname is unable to access VOB data in this situation. |
In deciding how to use views, bear in mind this capsule summary of the discussion in the preceding sections. When using ClearCase data, you must use a view — without a view context, a process or pathname cannot “see into” a VOB. A pathname can acquire a view context in several ways:
dSymbolic links (either UNIX-level links or VOB symbolic links) can cause unexpected behavior if you have not set a view. For example, suppose your file system includes this symbolic link:
% ls -l /vobs/aardvark /vobs/aardvark -> /vobs/all_projects/aardvark |
If your shell is not set to a view, you might attempt to visit the aardvark VOB with this command:
% cd /view/gamma/vobs/aardvark/src |
But the component-by-component resolution of the pathname by the OS kernel effectively transforms this command to:
% cd /vobs/all_projects/aardvark/src |
By specifying a full pathname, the symbolic link “pops you out” of the gamma working directory view context. And because your shell is not set to a view, the pathname will have no view context at all, and thus will fail.
The same analysis applies to view-extended pathname. For example, changing the command from cd to cat or ls in the above scenario would produce the same failure to access ClearCase data.
In consideration of this behavior, avoid creating UNIX-level or VOB-level symbolic links whose texts are full pathnames — use relative pathnames only. For example:
% ls -l /vobs/aardvark /vobs/aardvark -> ../all_projects/aardvark |
For more on this topic, see the pathnames_ccase manual page.
[1] Actually, a view can have different tags in different network regions; and it can have multiple tags within the same region. Taking advantage of this flexibility increases the likelihood of user confusion, though.