Rational Build Forge and Rational ClearCase

Additional setup requirements for ClearCase adaptors

See Adaptor requirements for general requirements. In addition to fulfilling the general requirements for adaptors, do the following:

1. Install a Build Forge agent on a host that can connect to the ClearCase server.
2. Install the ClearCase full client on the agent host.
3. Set up the environment for the agent so that commands can be run through the ClearCase client.
4. Determine how to implement and how and when to start the ClearCase views that are required. The provided templates assume the use of dynamic views and include starting that view when they run a cleartool command. Install the ClearCase full client on the agent host.

ClearCase views

• Dynamic views: Dynamic views allow you to see latest version of elements in the VOBs you specify without copying them to your local system. They must be started. You specify the VOBs to mount in the view.
• Snapshot views: Snapshot views are a copy of the repository. You can specify the version of objects to use. Snapshot views must be manually updated in order to get the latest items that have been checked in.

Dynamic Views

Dynamic views show a workspace that is constantly updated whenever anything is changed in the view context that you choose to see. Only elements that you check out are copied to your workspace, and you must check them in to make the available to other users. When you use dynamic views, you use three specifications to access the data you want:

• View: defines the list of versions to present (through a config spec). The view must be started using a command. It is represented on your local disk as a root directory for content. It is also called the view root. The commonly used directories are as follows:
  • Windows: drive M:, a shared drive
  • UNIX or Linux: /view, a mounted file system
• View context: defines a directory of content to use through a view tag. The view tag is defined in ClearCase. The directory becomes available to you when the view is started.
• VOB (versioned object base): defines a subdirectory of the view context. VOBs are defined in ClearCase. You mount a VOB in the view context explicitly. This subdirectory contains the versioned artifacts (source files and other artifacts).

Paths to a VOB on your local machine are built up out of those three items:

• Example path for Windows systems, using the default: M:\view_tag\vob_name
• Example path for UNIX and Linux systems, using the default: /view/view_tag/vob_name

Snapshot Views

When you use snapshot views, you specify the view context and must also load the data. You then have a local copy of all of the data you specify. Snapshot views must be reloaded in order to get changes that were checked in since you last loaded data.

Rational Build Forge features that support dynamic views

CLEARCASE_VIEW

Starts the specified ClearCase view. The view specified in this variable must exist, and the step using this variable must be set to "absolute". On systems running Microsoft Windows, this variable must be used along with the cc_suppress_server_root parameter for the agent in bfagent.conf.

_CLEARCASE_VIEWS

Specifies a list of ClearCase views to start before command execution. Set the value to a comma-separated list of views; for example, "View1,View2,View3".

_CLEARCASE_VOBS

Specifies a list of ClearCase VOBs to mount before command execution. Set the value to a comma-separated list of VOBs; for example, "\Vob1,\Vob2,\Vob3".

You may also need to use agent parameters to manage views on the agent host. Agent parameters must be set if the agent you are using with ClearCase is running on a Windows system. The are also useful if the view root you want to use through this agent is different than the view root set by the job. This would happen if you used the job for more than one agent and the specifications need to be different on each agent host system.

ccviewroot root-path

Specifies the default view root for this host. See ClearCase documentation on init for more information. The internal defaults are as follows:

• Windows systems: ccviewroot M:
• UNIX or Linux systems: ccviewroot /view

cc_suppress_server_root

If set, then the view path is the path set by ccviewroot. If not set, then the path set in the server definition is appended to the path set by ccviewroot. This setting does not need a value. If it is present in bfagent.conf, then it is set.

ClearCase adaptor template samples

The following adaptor template samples are provided.

ClearCaseBaseline

1. Scans a directory in a ClearCase view.
2. Writes branch and version information reported by ClearCase to the BOM report.

Variables used:

• INT_STREAM
• VIEW
• PROJECT_VOB
• CCSERVER
• UNIXCLIENT

ClearCaseByBaselineActivities

1. Creates a new baseline from the contents of a ClearCase view.
2. Compares the new baseline and the baseline from the previous adaptor execution to identify change activity.
3. For each change activity, writes the following information to the BOM report: activity, files changed, user, date, comments, and version.
4. For each changed file, writes change details (from diff command output) to the BOM report.

Variables used:

• CurDate
• LAST_RUN
• BASELINE
• VIEW
• VOB_PATH
• PROJECT_VOB
• CCSERVER
• UNIXCLIENT

ClearCaseByBaselineVersions

1. Creates a new baseline from the contents of a ClearCase view.
2. Compares the new baseline and the baseline from the previous adaptor execution to identify changed files.
3. For each changed file, writes the following information to the BOM report: file name, version, date, user, and comments.
4. For each changed file, writes change details (from diff command output) to the BOM report.

Variables used:

• CurDate
• LAST_RUN
• LABEL
• BASELINE
• VIEW
• VOB_PATH
• PROJECT_VOB
• CCSERVER
• UNIXCLIENT
• _CHAR_NATIVE

ClearCaseByDate

1. Queries a ClearCase view for changes between two dates. The default dates are the current timestamp and the timestamp of the previous adaptor execution.
2. For each changed file, writes the following information to the BOM report: file name, version, date, user, and comments.
3. For each changed file, writes change details (from diff command output) to the BOM report.

Variables used:

• CurDate
• LAST_RUN
• LABEL
• BASELINE
• VIEW
• VOB_PATH
• PROJECT_VOB
• CCSERVER
• UNIXCLIENT
• _CHAR_NATIVE

ClearCaseByLabel

1. Creates and applies a new label to the contents of a ClearCase view.
2. Compares the new label and the label from the previous adaptor execution to identify changed files.
3. For each changed file, writes the following information to the BOM report: file name, version, date, user, and comments.
4. For each changed file, writes change details (from diff command output) to the BOM report.

Variables used:

• CurDate
• LAST_RUN
• LABEL
• BASELINE
• VIEW
• VOB_PATH
• PROJECT_VOB
• CCSERVER
• UNIXCLIENT
• _CHAR_NATIVE

ClearCase adaptor variables

This table is a reference for the variable lists for the adaptor templates.

The following trigger variables may also be used to start views and mount vobs. However, they are independent of the views and vobs that are set in the adaptor variables.

• CLEARCASE_VIEW
• _CLEARCASE_VIEWS
• _CLEARCASE_VOBS

See Trigger variables reference.