ClearCase Reference Manual, Release 4.0, Windows

mklabel

Attaches version labels to versions of elements

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

Attach label to specified versions:

mklabel [ -rep·lace ] [ -r·ecurse ] [ -ver·sion version-selector ]

[ -c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment ]
label-type-selector pname ...
Attach label to versions listed in configuration record:

mklabel [ -rep·lace ] [ -c·omment comment | -cfi·le comment-file-pname |-cq·uery

| -cqe·ach | -nc·omment ]
[ -sel·ect do-leaf-pattern ] [ -ci ] [ -typ·e { f | d } ... ]
[ -nam·e tail-pattern ] -con·fig do-pname label-type-selector

DESCRIPTION

The mklabel command attaches a version label to one or more versions. You can attach a label to only one version of a particular element. You can specify the versions themselves on the command line, or you can specify a particular derived object. In the latter case, mklabel labels some or all the versions that were used to build that derived object.

Referencing Labeled Versions

Labeling a version of an element can affect the way the element appears in views. It also provides a new way to access the version with a version-extended pathname.

Version Selection by Views. A typical config spec rule uses version labels to select versions:

element * BASELEVEL_1

If you attach version label BASELEVEL_1 to a version of element foo.c, any view configured with this rule selects the labeled version (unless some rule earlier in the config spec matches another version of foo.c).

Version Labels in Version-Extended Pathnames. Labeling a version effectively adds a new hard link to the version in ClearCase extended namespace. If you attach version label R4.1A to version\main\rls4\12 of element bar.c, these pathnames are equivalent:

bar.c@@\main\rls4\12 bar.c@@\main\rls4\R4.1A

In addition, a third pathname is usually equivalent:

barc@@\R4.1A

This version-extended pathname is valid if it is unambiguous, that is, if no other version of bar.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.)

PERMISSIONS AND LOCKS

Permissions Checking: For each object processed, you must be one of the following: element group member, element owner, VOB owner, member of the ClearCase group. See the permissions reference page.

Locks: An error occurs if any of the following objects are locked: VOB, element type, element, branch type, branch, label type.

OPTIONS AND ARGUMENTS

MOVING A VERSION LABEL. Default: An error occurs if a version label of this type is already attached to some other version of the same element.

-rep·lace: Removes an existing label of the same type from another version of the element:

From another version on the same branch, if label-type-name was created with mklbtype -pbranch

From another version anywhere in the element's version tree, if label-type-name was not created with mklbtype -pbranch

: No error occurs if there is no such label to remove, but the label is attached to all versions specified in the command.

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by your .clearcase_profile file (default: -nc). See CUSTOMIZING COMMENT HANDLING in the comments reference page. Comments can be edited with chevent.

-c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment: Overrides the default with the option you specify. See the comments reference page.

SPECIFYING THE LABEL TYPE. Default: None.

label-type-selector: A label type, previously created with mklbtype. The label type must exist in each VOB containing a version to be labeled, or (if label-type-selector is a global type) in the Admin VOB hierarchy associated with each VOB. Specify label-type-selector in the form [lbtype:]type-name[@vob-selector]

type-name

Name of the label type

See the Object Names section in the cleartool reference page for rules about composing names.

vob-selector

VOB specifier

Specify vob-selector in the form [vob:]pname-in-vob

pname-in-vob

Pathname of the VOB-tag (whether or not the VOB is mounted) or of any file-system object within the VOB (if the VOB is mounted)

DIRECTLY SPECIFYING THE VERSIONS TO BE LABELED. The options and arguments in this section specify elements and their versions directly on the command line. Do not use these options and arguments when using a derived object to provide a list of versions.

pname ...: (Required) One or more pathnames, indicating versions to be labeled:

A standard or view-extended pathname to an element specifies the version selected in the view.

A version-extended pathname specifies a version, independent of view.

: Use -version to override these interpretations of pname.

: NOTE: mklabel differs from some other commands in its default handling of directory element pname arguments: it labels the directory element itself; it does not label the elements cataloged in the directory (unless you specify -recurse).

-ver·sion version-selector: For each pname, attaches the label to the version specified by version-selector. This option overrides both version-selection and version-extended naming. See the version_selector reference page for syntax details.

-r·ecurse: Processes the entire subtree of each pname that is a directory element (including pname itself). VOB symbolic links are not traversed during the recursive descent into the subtree.

USING A DERIVED OBJECT TO SPECIFY THE VERSIONS TO BE LABELED. The options and arguments in this section specify versions by selecting them from the configuration records associated with a particular derived object. Do not use these options when specifying elements and versions directly on the command line.

NOTE: Derived objects are created only in dynamic views.

-con·fig do-pname: (Required) Specifies one derived object. A standard pathname or view-extended pathname specifies the DO that currently appears in a view. To specify a DO independent of view, use an extended name that includes a DO-ID (for example, hello.obj@@24-Mar.11:32.412) or a version-extended pathname to a DO version.

: With the exception of checked-out versions, mklabel labels all the versions that would be included in a catcr -long -flat -element_only listing of that derived object. Note that this includes the following objects:

Any DO created by the build and subsequently checked in as a DO version.

Any file in the CR that was view-private at the time of the build, was converted to an element after the creation of the CR, and has at least one checked-in version.

: If the DO's configuration includes multiple versions of the same element, only the most recent version is labeled.

Use the following options to modify the list of versions to be labeled.

-sel·ect do-leaf-pattern

-ci

-typ·e { f | d } ...

-nam·e tail-pattern: Modify the set of versions to be labeled in the same way that these options modify a catcr listing. See the catcr reference page for details, and also the EXAMPLES section.

EXAMPLES

Examples including wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

Create a label type named REL6. Attach that label to the version of the current directory selected by your view, and to the currently selected version of each element in and below the current directory.

cmd-context mklbtype -nc REL6 Created label type "REL6".

cmd-context mklabel -recurse REL6 .

Created label "REL6" on "." version "\main\4". Created label "REL6" on ".\bin" version "\main\1". Created label "REL6" on ".\include" version "\main\1". Created label "REL6" on ".\libs" version "\main\2". Created label "REL6" on ".\lost+found" version "\main\0". Created label "REL6" on ".\release" version "\main\1". Created label "REL6" on ".\src" version "\main\6". Created label "REL6" on ".\src\Makefile" version "\main\2". Created label "REL6" on ".\src\cm_add.c" version "\main\1". Created label "REL6" on ".\src\convolution.c" version "\main\4". Created label "REL6" on ".\src\edge.sh" version "\main\1". . . .

Attach label REL1 to the version of msg.c in the view.

cmd-context mklabel REL1 msg.c

Created label "REL1" on "msg.c" version "\main\1".

Attach label REL2 to version 3 on the rel2_bugfix branch of file util.c.

cmd-context mklabel -version \main\rel2_bugfix\3 REL2 util.c Created label "REL2" on "util.c" version "\main\rel2_bugfix\3".

Move label REL2 to a different version of element hello.c, using a version-extended pathname to indicate that version.

cmd-context mklabel -replace REL2 hello.c@@\main\4 Moved label "REL2" on "hello.c" from version "\main\3" to "\main\4".

Attach label REL3 to each version that was used to build derived object .hello.obj. Note that both directories and files are labeled.

cmd-context mklabel -config hello.obj REL3 Created label "REL3" on "\users_hw\" version "\main\1". Created label "REL3" on "\users_hw\src" version "\main\2". Created label "REL3" on "\users_hw\src\hello.c" version "\main\3". Created label "REL3" on "\users_hw\src\hello.h" version "\main\1".

Attach label REL5 to each C-language source file version that was used to build derived object hello.exe.

cmd-context mklabel -config hello.exe -name '*.c' REL5 Created label "REL5" on "\users_hw\src\hello.c" version "\main\3". Created label "REL5" on "\users_hw\src\util.c" version "\main\1".

Attach label REL5 to all versions in the VOB mounted at \users_hw that were used to build derived object hello.exe.

cmd-context mklabel -config hello.exe -name '\users_hw\...' REL5 Created label "REL5" on "\users_hw\" version "\main\1". Created label "REL5" on "\users_hw\src" version "\main\2". Created label "REL5" on "\users_hw\src\hello.c" version "\main\3". Created label "REL5" on "\users_hw\src\hello.h" version "\main\1". Created label "REL5" on "\users_hw\src\util.c" version "\main\1".