mkbl

Creates a baseline or set of baselines

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • VersionVault: create a baseline of a component or set of baselines of components:
    mkbl [ –c/omment comment | –cfi/ le pname | –cq/ uery| –nc/omment ]
    [ –com/ponent component-selector[,...]

    [ –ide/ntical ] | –all [ –ide/ntical ] | –act/ivities activity-selector[,...] ]

    [ –nla/bel | –inc/remental | –fu/ll ] [ –vie/w view-tag ]

    baseline-root-name

  • VersionVault remote client: create a baseline of a component or set of baselines of components:
    mkbl [ –c/omment comment | –cq/ uery| –nc/omment ]
    [ –com/ponent component-selector[,...]

    [ –ide/ntical ] | –all [ –ide/ntical ] | –act/ivities activity-selector[,...] ]

    [ –nla/bel | –inc/remental | –fu/ll ] [ –vie/w view-tag ]

    baseline-root-name

  • VersionVault: create or change the dependency relationships for a composite baseline:
    mkbl [ –c/omment comment | –cfi/ le pname | –cq/ uery| –nc/omment ]
    –com/ponent component-selector [ –vie/w view-tag ]

    { [ –adep/ends_on depend-component-selector[,...] ]

    [ –ddep/ends_on depend-component-selector[,...] ] }

    [ –nla/bel | –inc/remental | –fu/ll ] [ –nac/t ]

    baseline-root-name

  • VersionVault: create a baseline by importing a label type:
    mkbl [ –c/omment comment | –cfi/ le pname | –cq/ uery| –nc/omment ]
    –imp/ort [ –com/ponent component-selector[,...] ] label-type-selector ...
  • VersionVault: create a baseline by cloning an existing baseline:
    mkbl [ –c/omment comment | –cfi/ le pname | –cq/ uery| –nc/omment ]
    –clone baseline-selector [ -view view-tag ] basename

Description

The mkbl command creates baselines or composite baselines. A baseline represents a snapshot of the changes made to a particular component in the context of a particular stream: it is a version of a component. For each element in the component, the baseline records the version of that element selected by the stream's configuration at the time mkbl is executed. The baseline also records the list of activities in the stream whose change sets contain versions of the component's elements.

A baseline selects one version of each element of a component. You can create multiple baselines per component, just as you can create multiple versions of an element. A baseline is associated with only one component, and you can only create one baseline per component per invocation of mkbl.

By default, all components that have been modified since the last full baseline are considered as candidates for new baselines. You can also create baselines for a subset of components in the stream or for components modified by specific activities.

If your project team works on multiple components, you may create a composite baseline. A composite baseline is a baseline that selects baselines in other components. You can use a composite baseline to represent the entire project baseline; this is easier than keeping track of a set of baselines, one for each component. Create a component for storing the composite baselines. (For information about how to create this type of component, see mkcomp.) In that component, create the composite baseline by adding member baselines with the –adepends_on option.

Initial baseline

When you create an ordinary component (that is, one that contains directories and elements), it includes an initial baseline whose name is of the form component-name_INITIAL. This baseline selects the /main/0 version of the component's root directory and serves as a starting point for successive baselines of the component.

Creating a baseline for an unmodified component

Use the –identical option to create a new baseline for a component that has not been modified. This can be useful in working with several components. You can create new baselines for a set of components regardless of whether they have been modified.

Creating baselines that include a set of activities

By default, all activities modified since the last baseline was made are captured in new baselines. You can select a subset of activities for inclusion in the baseline. If there are dependencies between the change sets of activities, you may not be able to include only the activity you want; you'll need to include the activities it depends on as well.

A single baseline is created if the selected activities are part of the same component. If an activity modifies more than one component, a new baseline is created for each component it modifies.

Creating a new composite baseline with existing dependency relationships

The operation of creating a new composite baseline is recursive. That is, the operation first creates baselines of its member components and then creates dependency references to those baselines in the composite. The result is a composite baseline that retains the dependency structure of its predecessor.

Creating or changing dependency relationships for a composite baseline

You can create or change the dependency relationships for a composite baseline by using the –adepends_on or –ddepends_on options. When a dependency reference to a component is added, a baseline of that component is made, if necessary. These operations apply only to direct members of a composite baseline and do not affect indirect members in a baseline hierarchy. A dropped component can still have a baseline that is lower in the dependency hierarchy.

Note: To change the existing dependency relationships, you must create a new composite baseline. You cannot change the relationships of an existing baseline with chbl.

Creating a baseline by importing a label

You can recognize a VOB as a component with the mkcomp command. When you do this, the VOB is given an initial baseline that selects the /main/0 version of the component root directory. However, this baseline does not automatically enable access to files and directories that are already in the VOB.

You can create a new baseline that corresponds to a set of labeled versions in the VOB or one of the VOB's components. To do this, use the –import option. The mkbl command creates a baseline that selects the labeled versions, making them accessible to the UCM project.

Before creating the baseline, be sure that the label is unlocked and ordinary (not global) and that labeled elements are checked in. Once the baseline is created, the label cannot be moved or removed except by privileged users. Be certain the label selects some version of all visible elements.

Baseline names

A baseline identifier is a user-specified baseline name to which a numeric extension is appended, if necessary, to make the baseline name unique in its PVOB. If you have defined a baseline name template for your project, baseline names will be created using that template. For information about defining a baseline name template, see mkproject and chproject.

The exceptions to the above rule are initial baselines and baselines created from a label. The name of an initial baseline is of the form component-name_INITIAL. When you create a baseline by importing a label, the basename is derived from the label's type selector. For example, the label-type selector REL1@/vobs/baz generates a baseline basename of REL1 whose scope is the baz component.

Baseline labels

You can choose whether versions of the baseline are to be labeled when the baseline is created. Baselines can be unlabeled, incrementally labeled, or fully labeled. After they are applied, baseline labels cannot be moved.

All baselines record a component's current configuration in a stream, but only labeled baselines can be used to configure other streams (by means of rebase or mkstream).

Choose a labeling scheme that suits your project's structure. Incremental baselines typically can be created more quickly than full baselines.

  • For a full baseline, the time required is proportional to the number of elements in the component.
  • For an incremental baseline, the time required is proportional to the number of elements changed since the last full baseline.

These options control labeling during baseline creation:

  • The –nlabel option, which creates an unlabeled baseline. Unlabeled baselines cannot be used as foundation baselines to configure a stream. They can be used with the diffbl command.
  • The –incremental option, which labels versions of elements that have changed since the last full baseline was created.
  • The –full option, which creates a baseline by selecting and labeling a version of each element in the component.

Each time when new baselines are made, mkbl checks to see whether any latest baselines are unlabeled. If any are found, mkbl issues a warning and displays the unlabeled baselines. You can change the labeling status for a baseline with the chbl command.

Promotion levels

Baselines are marked with a promotion level that signifies the quality of the baseline. When created, a project VOB is assigned an ordered set of promotion levels, one of which is designated the default promotion level, which is the level assigned to new baselines when they are created.

For more information, see setplevel.

Restrictions

Identities

No special identity required.

Locks

An error is generated if there is a lock on the project VOB. If you are importing a label type, an error is generated if that label type is locked.

Mastership

(Replicated VOBs only) Your current replica must master the stream where you make the baseline. When you create an imported baseline from a pre-UCM label, your current replica must master the component and label type.

Options and arguments

Event records and comments

Default
Creates one or more event records, with commenting controlled by your .versionvault_profile file (default: –cq). See 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 components

Default
–all
–com/ponent component-selector[,...]
Specifies the components for which baselines are made.

component-selector is of the form [component:]component-name[@vob-selector], where vob-selector specifies the component's project VOB.

–all
Creates a baseline for each component in the project that has been modified since the last baseline.
–ide/ntical
Creates new baselines for all components, regardless of whether they have been modified.

Specifying the activities

Default
All activities with changes that are not recorded in the last baselines are recorded in the new baselines.
–act/ivities activity-selector, ...
Specifies a list of activities to include in the new baselines.

activity-selector is of the form [activity:]activity-name[@vob-selector] where vob-selector specifies the activity's project VOB.

You can use this option to include only a subset of the unrecorded changes in the new baselines. A baseline is created for each component that has unrecorded changes in the specified list of activities.

The list of activities must be complete. That is, they must not depend on the inclusion of any other activities. Activity A2 is dependent on activity A1 if they both contain versions of the same element and A2 contains a later version than A1. If the list of activities is incomplete, the operation fails and lists the required activities.

Selecting labeling behavior

Default
–incremental.
–nla/bel
Specifies that versions for this baseline are not labeled. Unlabeled baselines cannot be used as foundation baselines, but can be used by the diffbl command and labeled later.
–inc/remental
Labels only versions that have changed since the last full baseline was created.
–fu/ll
Labels all versions visible below the component's root directory.

Specifying the view and stream

Default
The stream to which the current view is attached.
–vie/w view-tag
Specifies the view from which to create baselines. Baselines are created in the stream that the view is attached to.

For example, if you are working in coyne_dev_view, but want to create a baseline from the configuration specified by the view coyne_integration_view, use –view coyne_integration_view. This option creates a baseline in the project's integration stream that includes all the checked-in versions contained in coyne_integration_view. If you do not specify view-tag, the current view is used.

Specifying the baseline root

Default
None.
baseline-root-name
Specifies the root portion of the baseline name. For rules about composing root names, see the cleartool reference page. Also see Baseline names. You are not required to specify a baseline-root-name if it is not included in the baseline name template.

Creating or changing dependency relationships for a composite baseline

Default
Creates a composite baseline that retains the dependency structure of its predecessor.
–com/ponent component-selector
Specifies the component whose dependency relationship you want to change. The component's currently selected baseline is used as the initial configuration.
–adep/ends_on depend-component-selector[,...]
Adds dependency references to the specified components for the composite baseline.
–ddep/ends_on depend-component-selector[,...]
Drops dependency references to the specified components for the composite baseline.
–nac/t
Makes a baseline only in the component specified by –component.

Specifying a label to import

Default
None.
–imp/ort [ –com/ponent component-selector[,...]] label-type-selector ...
Creates a baseline using versions marked with the specified label-type-selector. The –component option is required when the label type is in a VOB that contains multiple components. The label type must be applied to the component's root directory and to every element below the root directory that you want to include in the component. Baselines are created as successors to the initial baseline. The scope of the label type must be ordinary, not global.

Cloning a baseline

Default
None.
–clone
Create a new baseline by cloning an existing baseline.
new-baseline-name
Specifies the name of a new baseline that is a clone of baseline-root-name.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you might 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 UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Create baselines for all components in the project that have been modified since the last baseline was created. The baseline name template, basename_stream_date, has been set in the project.

    cmd-context mkbl CITTEST
    Created baseline "CITTEST.BL14_mprent_mck.1_021903.1543" in
    component "webo_modeler".
    Begin incrementally labeling baseline
    "CITTEST.BL14_mprent_mck.1_021903.1543".
    Done incrementally labeling baseline
    "CITTEST.BL14_mprent_mck.1_021903.1543".
    Created baseline "CITTEST.BL14_mprent_mck.1_021903.1524" in
    component "webo_gui".
    Begin incrementally labeling baseline
    "CITTEST.BL14_mprent_mck.1_021903.1524".
    Done incrementally labeling baseline
    "CITTEST.BL14_mprent_mck.1_021903.1524".

  • Create baselines for the components modified by a particular activity.

    cmd-context mkbl -activities line-lib@\pvob1 BL2

  • Create a baseline for a component compx by importing a label type.

    cmd-context mkbl -c "Import BL2 label" –import  BL2@/vobs/xroutines
    Created baseline "BL2_compx_IMPORT" in component "compx" from lbtype BL2.

  • Create a baseline by importing a label type for a component whose root directory is one level beneath the VOB's root directory.

    cmd_context mkbl -import -comp comp2@/export/home/mprent/vobs/mpvob RE
    Created baseline "RE_comp2_IMPORT" in component "comp2" from lbtype RE.