Apache Ant ClearCase Tasks

by:
Curtis White (cwhite at aracnet dot com),
Sean P. Kane (spkane at genomatica dot com),
Rob Anderson (Anderson.Rob at vectorscm dot com), and
Sean Egan (sean at cm-logic dot com)

Version 1.6 - 02/25/2003

ClearCase Support

Table of Contents

Introduction

Apache Ant provides several optional tasks for working with ClearCase. These tasks correspond to various ClearCase commands using the Cleartool program. The current tasks available for Ant correspond to only a few of the significant ClearCase commands.

More tasks can be easily added by deriving from the ClearCase class and then adding functionality that is specific to that ClearCase command.

Important: these tasks all require cleartool on the command line. If a task fails with an IOException, especially error code 2 on Windows, this is your problem.

CCCheckin

Description

Task to perform a "cleartool checkin" command to ClearCase.

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on No
comment Specify a comment. Only one of comment or commentfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or commentfile may be used. No
nowarn Suppress warning messages No
preservetime Preserve the modification time No
keepcopy Keeps a copy of the file with a .keep extension No
identical Allows the file to be checked in even if it is identical to the original No
failonerr Throw an exception if the command fails. Default is true No

Examples

<cccheckin viewpath="c:/views/viewdir/afile"
        commentfile="acomment.txt"
        nowarn="true"
        identical="true"/>

Does a ClearCase checkin on the file c:/views/viewdir/afile. Comment text from the file acomment.txt is added to ClearCase as a comment. All warning messages are suppressed. The file is checked in even if it is identical to the original.

CCCheckout

Description

Task to perform a "cleartool checkout" command to ClearCase.

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on No
reserved Specifies whether to check out the file as reserved or not Yes
out Creates a writable file under a different filename No
nodata Checks out the file but does not create an editable file containing its data No
branch Specify a branch to check out the file to No
version Allows checkout of a version other than main latest No
nowarn Suppress warning messages No
comment Specify a comment. Only one of comment or commentfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or commentfile may be used. No
notco Fail if it's already checked out to the current view. Set to false to ignore it.
Since ant 1.6.1		 No
failonerr Throw an exception if the command fails. Default is true.
Since ant 1.6.1		 No

Examples

<cccheckout viewpath="c:/views/viewdir/afile"
        reserved="true"
        branch="abranch"
        nowarn="true"
        comment="Some comment text"/>

Does a ClearCase checkout on the file c:/views/viewdir/afile. It is checked out as reserved on branch called abranch. All warning messages are suppressed. A Some comment text is added to ClearCase as a comment.

CCUnCheckout

Description

Task to perform a UnCheckout command to ClearCase.

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on No
keepcopy Specifies whether to keep a copy of the file with a .keep extension or not No
failonerr Throw an exception if the command fails. Default is true
Since ant 1.6.1		 No

Examples

<ccuncheckout viewpath="c:/views/viewdir/afile"
        keepcopy="true"/>

Does a ClearCase uncheckout on the file c:/views/viewdir/afile. A copy of the file called c:/views/viewdir/afile.keep is kept.

CCUpdate

Description

Task to perform an "cleartool update" command to ClearCase.

Parameters

Attribute Values Required
viewpath Path to the ClearCase snapshot view file or directory that the command will operate on No
graphical Displays a graphical dialog during the update No
log Specifies a log file for ClearCase to write to No
overwrite Specifies whether to overwrite hijacked files or not No
rename Specifies that hijacked files should be renamed with a .keep extension No
currenttime Specifies that modification time should be written as the current time. Either currenttime or preservetime can be specified. No
preservetime Specifies that modification time should preserved from the VOB time. Either currenttime or preservetime can be specified. No
failonerr Throw an exception if the command fails. Default is true.
Since ant 1.6.1		 No

Examples

<ccupdate viewpath="c:/views/viewdir"
        graphical="false"
        log="log.log"
        overwrite="true"
        currenttime="true"
        rename="false"/>

Does a ClearCase update on the snapshot view directory c:/views/viewdir. A graphical dialog will be displayed. The output will be logged to log.log and it will overwrite any hijacked files. The modified time will be set to the current time.

CCMklbtype

Description

Task to perform a "mklbtype" command to ClearCase.

Parameters

Attribute Values Required
typename Name of the label type to create Yes
vob Name of the VOB No
replace Replace an existing label definition of the same type No
global Either global or ordinary can be specified, not both. Creates a label type that is global to the VOB or to VOBs that use this VOB No
ordinary Either global or ordinary can be specified, not both. Creates a label type that can be used only in the current VOB. Default No
pbranch Allows the label type to be used once per branch in a given element's version tree No
shared Sets the way mastership is checked by ClearCase. See ClearCase documentation for details No
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
failonerr Throw an exception if the command fails. Default is true
Since ant 1.6.1		 No

Examples

<ccmklbtype typename="VERSION_1"
        ordinary="true"
        comment="Development version 1"/>

Does a ClearCase mklbtype to create a label type named VERSION_1. It is created as ordinary so it is available only to the current VOB. The text Development version 1 is added as a comment.

CCMklabel

Description

Task to perform a "mklabel" command to ClearCase.

Parameters

Attribute Values Required
typename Name of the label type Yes
viewpath Path to the ClearCase view file or directory that the command will operate on No
replace Replace a label of the same type on the same branch No
recurse Process each subdirectory under viewpath No
version Identify a specific version to attach the label to No
vob Name of the VOB No
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
failonerr Throw an exception if the command fails. Default is true
Since ant 1.6.1		 No

Examples

<ccmklabel viewpath="c:/views/viewdir/afile"
        comment="Some comment text"
        recurse="true"
        version="\main\2"
        typename="VERSION_1"/>

Does a ClearCase mklabel on the file c:/views/viewdir/afile under the main branch for version 2 (\main\2). Text Some comment text is added as a comment. It will recurse all subdirectories.

CCRmtype

Description

Task to perform a "rmtype" command to ClearCase.

Parameters

Attribute Values Required
typekind The kind of type to create. Valid types are:
attype
brtype
eltype
hltype
lbtype
trtype 		-
-
-
-
-
- 		attribute type
branch type
element type
hyperlink type
label type
trigger type
Yes
typename The name of the type to remove Yes
ignore Used with trigger types only. Forces removal of trigger type even if a pre-operation trigger would prevent its removal No
rmall Removes all instances of a type and the type object itself No
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
failonerr Throw an exception if the command fails. Default is true Since ant 1.6.1 No

Examples

<ccrmtype typekind="lbtype"
        typename="VERSION_1"
        commentfile="acomment.txt"
        rmall="true"/>

Does a ClearCase rmtype to remove a label type (lbtype) named VERSION_1. Comment text from the file acomment.txt is added as a comment. All instances of the type are removed, including the type object itself.

CCLock

Description

Task to perform a "cleartool lock" command to ClearCase.

Parameters

Attribute Values Required
replace Specifies replacing an existing lock No
nusers Specifies user(s) who can still modify the object No
obsolete Specifies that the object should be marked obsolete No
comment Specifies how to populate comments fields No
pname Specifies the object pathname to be locked. No
objselect This variable is obsolete. Should use objsel instead. No
objsel Specifies the object(s) to be locked.
Since ant 1.6.1		 No
failonerr Throw an exception if the command fails. Default is true.
Since ant 1.6.1		 No

Examples

<cclock
    objsel="stream:Application_Integration@\MyProject_PVOB"
    />

Does a ClearCase lock on the object stream:Application_Integration@\MyProject_PVOB.

CCUnlock

Description

Task to perform a "cleartool unlock" command to ClearCase.

Parameters

Attribute Values Required
comment Specifies how to populate comments fields No
pname Specifies the object pathname to be unlocked. No
objselect This variable is obsolete. Should use objsel instead. No
objsel Specifies the object(s) to be unlocked.
Since ant 1.6.1		 No
failonerr Throw an exception if the command fails. Default is true.
Since ant 1.6.1		 No

Examples

<ccunlock
    objsel="stream:Application_Integration@\MyProject_PVOB"
    />

Does a ClearCase unlock on the object stream:Application_Integration@\MyProject_PVOB.

CCMkbl

Description

Task to perform a "cleartool mkbl" command to ClearCase.

Parameters

Attribute Values Required
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
baselinerootname Specify the name to be associated with the baseline. Yes
nowarn Suppress warning messages No
identical Allows the baseline to be created even if it is identical to the previous baseline. No
full Creates a full baseline. No
nlabel Allows the baseline to be created without a label. No
failonerr Throw an exception if the command fails. Default is true.
Since ant 1.6.1		 No

Examples

<ccmkbl
    baselinerootname="Application_Baseline_AUTO"
    identical="yes"
    full="no"
    viewpath="v:\ApplicationCC"
    />

Does a ClearCase mkbl on the Integration view at v:\ApplicationCC even if it is identical to a previous baseline. The new baseline with be incremental and named "Application_Baseline_AUTO".

CCMkattr

Description

Task to perform a "cleartool mkattr" command to ClearCase.
Since ant 1.6.1

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on Yes
replace Replace the value of the attribute if it already exists No
recurse Process each subdirectory under viewpath No
version Identify a specific version to attach the attribute to No
typename Name of the attribute type Yes
typevalue Value to attach to the attribute type Yes
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
failonerr Throw an exception if the command fails. Default is true No

Examples

<ccmkattr viewpath="c:/views/viewdir/afile"
    typename="BugFix"
    typevalue="34445"
    />

Does a ClearCase mkattr on the file c:/views/viewdir/afile and attaches the attribute BugFix with a value of 34445 to it.

CCMkdir

Description

Task to perform a "cleartool mkdir" command to ClearCase.
Since ant 1.6.1

Parameters

Attribute Values Required
viewpath Path to the ClearCase view directory that the command will operate on Yes
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
nocheckout Do not checkout after element creation No
failonerr Throw an exception if the command fails. Default is true No

Examples

<ccmkdir viewpath="c:/views/viewdir/adir"
        nocheckout="true"
        comment="Some comment text"/>

Does a ClearCase mkdir on the dir c:/views/viewdir/adir and does not automatically check it out.

CCMkelem

Description

Task to perform a "cleartool mkelem" command to ClearCase.
Since ant 1.6.1

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on Yes
comment Specify a comment. Only one of comment or cfile may be used. No
commentfile Specify a file containing a comment. Only one of comment or cfile may be used. No
nowarn Suppress warning messages No
nocheckout Do not checkout after element creation No
checkin Checkin element after creation No
preservetime Preserve the modification time (for checkin) No
master Assign mastership of the main branch to the current site No
eltype Element type to use during element creation No
failonerr Throw an exception if the command fails. Default is true No

Examples

<ccmkelem viewpath="c:/views/viewdir/afile"
        eltype="text_file"
        checkin="true"
        comment="Some comment text"/>

Does a ClearCase mkelem on the file c:/views/viewdir/afile with element type text_file. It also checks in the file after creation.