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=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 No; only one of the two may be used
commentfile Specify a file containing a comment
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 No; default is true

Examples

Perform 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.

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

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 (or whatever is selected by a config spec) No
nowarn Suppress warning messages No
comment Specify a comment No; only one of the two may be used
commentfile Specify a file containing a comment
notco Fail if it's already checked out to the current view. Set to false to ignore it.
Since Ant 1.6.1
No; default is true
failonerr Throw an exception if the command fails.
Since Ant 1.6.1
No; default is true

Examples

Perform 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.

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

CCUnCheckout

Description

Task to perform a cleartool 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.
Since Ant 1.6.1
No; default is true

Examples

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

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

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. Mutually exclusive with preservetime. No
preservetime Specifies that modification time should preserved from the VOB time. Mutually exclusive with currenttime. No
failonerr Throw an exception if the command fails.
Since Ant 1.6.1
No; default is true

Examples

Perform 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.

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

CCMklbtype

Description

Task to perform a cleartool 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 Creates a label type that is global to the VOB or to VOBs that use this VOB. No; only one of the two may be used, default ordinary=true
ordinary Creates a label type that can be used only in the current VOB.
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 No; only one of the two may be used
commentfile Specify a file containing a comment
failonerr Throw an exception if the command fails.
Since Ant 1.6.1
No; default is true

Examples

Perform 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.

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

CCMklabel

Description

Task to perform a cleartool 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 No; only one of the two may be used
commentfile Specify a file containing a comment
failonerr Throw an exception if the command fails.
Since Ant 1.6.1
No; default is true

Examples

Perform 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.

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

CCRmtype

Description

Task to perform a cleartool rmtype command to ClearCase.

Parameters

Attribute Values Required
typekind The kind of type to create. Valid types are:
Kind Description
attype attribute type
brtype branch type
eltype element type
hltype hyperlink type
lbtype label type
trtype 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 No; only one of the two may be used
commentfile Specify a file containing a comment
failonerr Throw an exception if the command fails. Since Ant 1.6.1 No; default is true

Examples

Perform 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.

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

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 Obsolete. 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.
Since Ant 1.6.1
No; default is true

Examples

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

<cclock objsel="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 Obsolete. 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.
Since Ant 1.6.1
No; default is true

Examples

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

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

CCMkbl

Description

Task to perform a cleartool mkbl command to ClearCase.

Parameters

Attribute Values Required
comment Specify a comment No; only one of the two may be used
commentfile Specify a file containing a comment
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.
Since Ant 1.6.1
No; default is true

Examples

Perform 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.

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

CCMkattr

Since Ant 1.6.1

Description

Task to perform a cleartool mkattr command to ClearCase.

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 No; only one of the two may be used
commentfile Specify a file containing a comment
failonerr Throw an exception if the command fails. No; default is true

Examples

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

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

CCMkdir

Since Ant 1.6.1

Description

Task to perform a cleartool mkdir command to ClearCase.

Parameters

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

Examples

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

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

CCMkelem

Since Ant 1.6.1

Description

Task to perform a cleartool mkelem command to ClearCase.

Parameters

Attribute Values Required
viewpath Path to the ClearCase view file or directory that the command will operate on Yes
comment Specify a comment No; only one of the two may be used
commentfile Specify a file containing a comment
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. No; default is true

Examples

Perform ClearCase mkelem on the file c:/views/viewdir/afile with element type text_file, check in the file after creation.

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