Table 2-1 lists all the cleartool subcommands, organized by function. The complete list can be quite daunting, because much of ClearCase's extensive feature set has been incorporated into this single tool. On a day-to-day basis, however, you'll probably use fewer than a dozen commands.

For example, the following set of cleartool subcommands fulfills a typical developer's day-to-day needs:

When you do need to use a cleartool subcommand with which you're not familiar, you can take advantage of several on-line help facilities:

You can use cleartool in either single-command mode or interactive mode. To invoke a single cleartool subcommand from the shell, use this syntax:

% cleartool subcommand [ options-and-args ]

When entering a series of subcommands, you may find it more convenient to type “cleartool” without any arguments. This places you at the interactive-mode prompt:

cleartool>

You can then issue any number of subcommands (simply called “commands” from now on), ending with quit to return to the shell. cleartool commands can be continued onto additional lines with the backslash (\) character, as with UNIX shells.

Command options may appear in any order, but all options must precede any non-option arguments (typically, names of files, versions, branches, and so on). If an option is followed by an additional argument, such as -branch /main/bugfix, there must be white space between the option string and the argument. If the argument itself includes space characters, it must be quoted.

Many subcommand names and option words can be abbreviated. A command's syntax summary indicates all valid abbreviations. For example:

lsc·heckout (in printed manual pages)
lsc/heckout (in on-line manual pages)

This means that you can abbreviate the subcommand name to the minimal “lsc”, or to any intermediate spelling: “lsch”, “lsche”, and so on.

A few cleartool commands have a built-in command alias. For example, checkin's alias is ci; similarly, checkout's alias is co. These commands are equivalent:

% cleartool checkin test.c
  and 
% cleartool ci test.c

cleartool commands use multiple-character options, such as - all, - default, and - comment. Long options can always be abbreviated; as with commands, the minimal abbreviation is always three characters or fewer, and any intermediate spelling is valid: you can abbreviate - delete to -del, -dele, or - delet.

Options that are commonly used in standard UNIX commands have single-letter abbreviations. For example, you can abbreviate -directory to -d. The others options in this category include -all, -recurse, -long, and -short.

Options rigorously distinguish between type objects and instances of those types. For example:

Many cleartool commands take one or more pathnames as arguments — typically, the name of a file or directory element, or a view-private file, or a derived object that you've built with clearmake. You can use either kind of standard UNIX pathname: full or relative. In many cases, you can also use a ClearCase extended pathname:

/vobs/proj/test.c                    (standard full pathname)
/view/akp/vobs/proj/test.c      (view-extended full pathname)
/vobs/proj/test.c@@/main/bugfix/4
                             (version-extended full pathname)
test.c                           (standard relative pathname)
test.c@@/RLS2.0          (version-extended relative pathname)
test.c@@/main/LATEST     (version-extended relative pathname)
../lib/libsort.a                 (standard relative pathname)
../lib/libsort.a@@/RLS4.2
                         (version-extended relative pathname)
hello.o                 (standard pathname to derived object)
hello.o@@14-Mar.09:55.4388		 
                        (extended pathname to derived object)

For both full or relative pathnames:

(Strictly speaking, the extended names for hyperlinks are not “pathnames”, since hyperlinks do not appear at all in the operating system's file namespace. Syntactically, however, cleartool treats hyperlink names like other pathnames.)

For more information on ClearCase pathnames, see the version_selector and pathnames_ccase manual pages.

In single-command mode, the cleartool command you enter is first processed by the UNIX shell. The shell expands file name patterns and environment variables, and it interprets quotes and other special characters. cleartool processes the resulting argument list directly, without any further interpretation.

In interactive mode, cleartool itself interprets the command line similarly, but not identically, to the UNIX shells. In particular, it does not expand environment variables and does not perform command substitution ( `...`). For details, see the cleartool manual page.

Each change to a VOB (checkin of a new version, attaching of a version label, and so on) is accompanied by the creation of an event record in the VOB database. Many cleartool commands allow you to annotate the event record(s) they create with a comment string. In some cases, your comment is appended to a ClearCase-generated comment. All commands that accept comment strings recognize the same options:

All cleartool commands that modify (“write”) a VOB are subjected to permissions checking. The following hierarchy is used, in a command-specific manner, to determine whether a command should proceed or be cancelled:

For example, the root user always has permission to use commands that modify a VOB. However, if you try to modify an element that you do not own, and are neither the VOB owner nor the root user, cleartool will not allow the operation to proceed.

ClearCase also provides for temporary access control through explicit locking of individual objects, with the lock command. When an object is locked, it cannot be modified by anyone (except, perhaps, for a list of explicitly-exempted users).

For details on permissions-checking and locks, see the ct_permissions manual page.

If you exit cleartool by entering a quit command in interactive mode, the exit status is 0. The exit status from single-command mode depends on whether the command succeeded (zero exit status) or generated an error message (nonzero exit status).

Some of the warning and error messages displayed by cleartool commands are also written to log files located in directory /usr/adm/atria/log. You may sometimes find that a message has been written to a log on another host; this is a artifact of ClearCase's client-server architecture.

You can invoke clearmake using the ClearCase CLI or GUI. The command-line interface is designed to be as similar as possible to other make variants. Single-letter command options have their familiar meanings. For example:

clearmake recognizes additional options (also single-letter) that control its enhanced functionality: configuration lookup, creation of configuration records and derived objects, parallel and distributed building, and so on. For a complete description, see the clearmake manual page.

You can run clearmake as a background process or invoke it from a shell script, just like any other program. (In clearmake output, some names are emboldened, for clarity. On some architectures, running clearmake in the background suppresses this emboldening, but no characters are lost.)

clearmake was designed to let developers in makefile-based build environments continue working in their accustomed manner. The following simple build scenario demonstrates how little adjustment is required to begin building with clearmake.

clearmake builds targets (or avoids building them) in a manner similar to, but more sophisticated than, other make variants. Figure 2-1 illustrates the results of a typical build:

Figure 2-1. `clearmake' Build Scenario

clearmake builds a new derived object for each newly-checked-out source file, because no other build could possibly have used your checked-out version.

---

Note: clearmake does not attempt to verify that you have actually edited the file; the checkout itself triggers the rebuild. As you work, each text-editor “save file” followed by an invocation of clearmake will cause a rebuild of the updated file's dependents, in the standard make manner.

---

For source files that you have not checked out, clearmake may or may not actually build a new derived object:

This manual contains a great deal more information on using clearmake and related software build mechanisms starting with Chapter 10, “Building with clearmake; Some Basic Pointers”.