BuildForge can work with Rational ClearCase for source
code management.
This topic describes additional setup requirements for integrating
with Rational ClearCase and summarizes the characteristics of the
provided sample adopter templates.
The ClearCase adaptor template samples provide methods of analyzing
changes to a baseline. Typically change analysis is used for build
avoidance: if a baseline component has not changed, it is not rebuilt
Additional setup requirements for ClearCase adaptors
See Adaptor requirements for general requirements. In addition to fulfilling
the general requirements for adaptors, do the following:
- Install a Build Forge agent on a host that can connect to the
ClearCase server.
- Install the ClearCase full client on the agent host.
- Set up the environment for the agent so that commands can be run
through the ClearCase client.
- 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
ClearCase employs views as
the means for you to access data. Two types of view can be used:
- 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
You can use special environment variables to define and
start dynamic views from a Build Forge job.
- 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
- Scans a directory in a ClearCase view.
- Writes branch and version information reported by ClearCase to
the BOM report.
Variables used:
- INT_STREAM
- VIEW
- PROJECT_VOB
- CCSERVER
- UNIXCLIENT
- ClearCaseByBaselineActivities
- Creates a new baseline from the contents of a ClearCase view.
- Compares the new baseline and the baseline from the previous adaptor
execution to identify change activity.
- For each change activity, writes the following information to
the BOM report: activity, files changed, user, date, comments, and
version.
- 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
- Creates a new baseline from the contents of a ClearCase view.
- Compares the new baseline and the baseline from the previous adaptor
execution to identify changed files.
- For each changed file, writes the following information to the
BOM report: file name, version, date, user, and comments.
- 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
- Queries a ClearCase view for changes between two dates. The default
dates are the current timestamp and the timestamp of the previous
adaptor execution.
- For each changed file, writes the following information to the
BOM report: file name, version, date, user, and comments.
- 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
- Creates and applies a new label to the contents of a ClearCase
view.
- Compares the new label and the label from the previous adaptor
execution to identify changed files.
- For each changed file, writes the following information to the
BOM report: file name, version, date, user, and comments.
- 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.
Environment variable name |
Description |
BASELINE |
For ByBaseline adaptors, when you use your adaptor
to generate differences by baseline, the system uses this value as
the baseline. |
CCSERVER |
Set this variable to the name of the host that
has the ClearCase client and Build Forge agent installed. |
CurDate |
Supplies the current date to the adaptor, using
a .date command to generate the date in the format expected by ClearCase.
Do not change this value. |
LABEL |
For ByLabel adaptors, when you use your adaptor
to generate differences by label (with the ByLabel adaptor), the system
uses this value as the label. |
LAST_RUN |
For ByDate adaptors, the system uses this value
to determine whether any changes have occurred; the value is the date
of the last successful run. You can manipulate this value when testing
the adaptor to force the adaptor to run, by picking a date that you
know precedes some changes. If the adaptor allows the run to continue,
it automatically updates this value to the current date. The default
value is 1-Jan-05.00:00:00. |
PROJECT_VOB |
When you use the ByBaseline adaptor, set this
variable to the name of your Project VOB (only used with UCM ClearCase).
Example: \ProjectVob |
UNIXCLIENT |
Used to set platform-specific information. Set
to 0 if the client is running on Windows. Set to 1 if the client is
running on UNIX or Linux. |
VIEW |
Set this variable to the name of the ClearCase
view that you want to use with the adaptor. |
VOB_PATH |
Set this value to the name of your component
VOB, and optionally, its subdirectories. Use a comma-separated list
for multiple names. |
_CHAR_NATIVE |
Used internally and always set to 1. |
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.