|Note: Much of the information in this section is available on-line, in the cleartool manual page.|
cleartool is the main CLI tool for interacting with your organization's data repository. cleartool has a rich set of subcommands, which create, modify, and manage the information in VOBs and views.
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.
display configuration specification
edit configuration specification
list VOB objects and view-private objects in a directory
list view-private objects
list view registry entries
create view-tag or VOB-tag
create and register a view
print working view
recover a view database
update the format of a view database
remove a view-tag and unregister a view on the local host
remove a view storage area or remove view-related records from a VOB
set the configuration specification
create a process that is set to a view
start or connect to a view_server process
Working with Version Tree Structures
create permanent new version of an element
create view-private, modifiable copy of a version
change the type of an element / rename a branch
describe VOB object
select objects from a directory hierarchy
create VOB hard link or VOB symbolic link
list version tree of an element
create a new branch in the version tree of an element
create a branch type object
create a directory element
create an element
create an element type object
move or rename an element or VOB link
convert a checkout to reserved status
remove a branch from the version tree of an element
remove an element from a VOB
remove the name of an element or VOB symbolic link from a directory
remove a version from the version tree of an element
cancel a checkout of an element
change a checkout to unreserved status
list version tree of an element graphically
display configuration record
compare configuration records
list derived objects
remove a derived object from a VOB
wink-in a derived object
list type objects
attach attributes to VOB objects
create an attribute type object
attach a hyperlink to a VOB object
create a hyperlink type object
attach version labels to versions
create a version label type object
remove an attribute from a VOB object
remove a hyperlink from a VOB object
remove a version label from a version
remove a merge arrow from versions
remove a type object from a VOB
rename a type object
Working with Event Records
modify comment string in existing event record(s)
list checkouts of an element
Working with the Contents of Versions
annotate lines of text file with timestamps
compare files or versions of an element
determine what files require a merge
merge files or versions of an element
compare files or versions of an element graphically
merge files or versions of an element graphically
change the storage pool to which an element is assigned
lock a VOB object
list storage pools
list view registry entries
list VOB registry entries
create a VOB storage pool or modify its scrubbing parameters
attach a trigger to an element
create a trigger type object
create and register a versioned object base
activate a VOB
change permissions or ownership of a VOB object
change owner or groups of a VOB
update the format of a VOB database
create an entry in the VOB storage registry or view storage registry
remove a storage pool from a VOB
remove trigger from an element
remove a VOB storage directory
rename a VOB storage pool
report on VOB disk space usage
deactivate a VOB
unlock a VOB object
remove a VOB or view from the storage registry
change current working directory
print working directory
help on cleartool command usage
display a ClearCase manual page
summary information on cleartool subcommands
quit interactive cleartool session
create a subprocess to run a shell or other specified program
to create a new view, and then adjust its configuration
to start working in a view
|checkout, checkin, uncheckout|
to create new version-controlled elements
|lscheckout, lshistory, lsvtree|
|diff, merge, findmerge|
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:
% cleartool help (syntax of all subcommands) % cleartool help mklabel (syntax of one subcommand) % cleartool mklabel -help (syntax of one subcommand)
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:
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.
Specifies a particular branch type object.
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)
The standard operating system pathname of an element implicitly references the version selected by your view.
The standard pathname of a derived object references the one built in your view. (Users in different views can build makefile targets independently; different derived objects produced by such builds appear at the same pathname in the respective views.)
A VOB-extended pathname references an object using VOB database identifier. The most commonly-used is a version-extended pathname, which references a particular version of an element using its unique version-ID (for example, test.c@@/main/bugfix/4) or using a version label (for example, test.c@@RLS2.0). Other kinds of VOB-extended pathnames include:
hello.c@@ (extended pathname to element object) hello.c@@/main/bugfix (extended pathname to branch object) hello.o@@14-Mar.09:55.4388 (extended pathname to derived object,) (incorporating a unique DO-ID) DesignFor@566 (extended pathname to hyperlink object) Merge@268 (incorporating a unique hyperlink-ID) SyncWith@4099
(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.)
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:
The command prompts for a comment, which will be placed in the event records for all objects processed by this command.
For each object it processes, this command prompts for a comment to be placed in the corresponding event record.
(“no additional comment”) For each object it processes, the command creates an event record with no user-supplied comment string.
cleartool includes several commands that display event records, optionally including the comment strings: lshistory, lscheckout, lstype, lslock, and lspool. See the fmt_ccase manual page for a description of the simple report-writing facility built into these commands.
Each command that accepts a comment string has comment default, which takes effect if you enter the command without any comment option. For example, the checkin command's comment default is -cqe, causing cleartool to prompt you to enter a comment for each element being checked in. The ln command's comment default is -nc: create the event record without a user-supplied comment.
You can customize cleartool's comment-handling with a user profile file, .clearcase_profile, in your home directory. For example, you might establish -cqe as the comment default for the ln command. See the user_profile manual page for details.
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:
the VOB owner (typically, the user who created the VOB storage area)
the owner of the element involved in the command
the creator of the type object (for modifications to objects of that type)
the creator of a particular version or derived object
members of an element's group or derived object's group (same UNIX group ID)
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).
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).
clearmake is the ClearCase build utility, designed to be compatible with many different make variants. We recommend that, you read Chapter 5, Building Software with ClearCase in the CASEVision™/ClearCase Concepts Guide, before reading this section.
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:
specify name of makefile
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.
(Strictly speaking, this is not required: if your process has a working directory view context, but not a set view context, clearmake automatically sets the view by executing a cleartool setview -exec clearmake command. See “Setting a View”.)
Go to a development directory — Change to a directory within any VOB.
Edit some source files — Typically, you need to edit some sources before performing a build; accordingly, you checkout some file elements and revise the checked-out versions.
% clearmake (build the default target) % clearmake cwd.o libproj.a (build one or more particular targets) % clearmake -k monet CFLAGS=-g (use standard options and make-macro overrides)
|Note: We recommend that you avoid specifying make-macro overrides on the command line. See “Using a Build Options Specification (BOS) File”.|
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:
|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.|
Sometimes, it reuses a derived object that already appears in your view, produced by a previous build.
Sometimes, clearmake winks-in an existing derived object originally built in another view. (It's even possible that a winked-in DO was originally created in your view, but then deleted — for example, by a “make clean”.)
Sometimes, changes to other aspects of your build environment trigger a clearmake rebuild: revision to a header file; change to the build script, use of a make-macro override; change to an environment variable used in the build script.
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”.