Google

Perforce Tasks User Manual

by

Version 1.1 - 2001/01/09


Contents


Introduction

These tasks provide an interface to the Perforce SCM. The org.apache.tools.ant.taskdefs.optional.perforce package consists of a simple framework to support p4 functionality as well as some Ant tasks encapsulating frequently used (by me :-) p4 commands. However, the addition of new p4 commands is a pretty simple task (see the source). Although it is possible to use these commands on the desktop, they were primarily intended to be used by automated build systems.

Note: These tasks require the oro 2.0.XXX regular expression package. Simply download this package and copy the jakarta-oro-2.0.XXX.jar file into Ant's lib directory. You will also need the Perforce client executable (p4 or p4.exe but not p4win.exe) in your path.

The Tasks

P4Sync Synchronise a workspace to a depot
P4Change Request a new changelist from the Perforce server
P4Edit Open files for edit (checkout)
P4Submit Submit a changelist to the Perforce server (checkin)
P4Have List current files in client view, useful for reporting
P4Label Create a label reflecting files in the current workspace
P4Counter Obtain or set the value of a counter
P4Reopen Move files between changelists
P4Revert Revert files
P4Add Add files

General P4 Properties

Each p4 task requires a number of settings, either through build-wide properties, individual attributes or environment variables. These are

Property Attribute Env Var Description Default
p4.port port P4PORT The p4d server and port to connect to perforce:1666
p4.client client P4CLIENT The p4 client spec to use The logged in username
p4.user user P4USER The p4 username The logged in username
-- view -- The client, branch or label view to operate upon. See the p4 user guide for more info. //...

Your local installation of Perforce may require other settings (e.g. P4PASSWD, P4CONFIG). At the moment, these can only be set outside of Ant, as environment variables.

Additionally, you may also specify the following attributes:

Attribute Description Required
failonerror Specifies whether to stop the build (true|yes|on) or keep going (false|no|off) if an error is returned from the p4 command. No; defaults to true.

Examples

Setting in the environment:-

(Unix csh)

setenv P4PORT myperforcebox:1666

(Unix sh et al)

P4USER=myp4userid; export P4USER

Using build properties:-

<property name="p4.client" value="nightlybuild"/>

Using task attributes:-


<p4Whatever

	port="myserver:1666"

	client="smoketest"

	user="smoketestdude"

	.

	.

	.

/>

For more information regarding the underlying 'p4' commands you are referred to the Perforce Command Reference available from the Perforce website.

Taskdefs

Standard taskdefs (for you to copy'n'paste) -- normally this is done automatically if you install this optional task.


    <taskdef name="p4sync" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Sync"/>

    <taskdef name="p4change" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Change"/>

    <taskdef name="p4edit" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Edit"/>

    <taskdef name="p4submit" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Submit"/>

    <taskdef name="p4have" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Have"/>

    <taskdef name="p4label" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Label"/>

    <taskdef name="p4counter" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Counter"/>

    <taskdef name="p4reopen" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Reopen"/>

    <taskdef name="p4revert" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Revert"/>

    <taskdef name="p4add" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Add"/>


Task Descriptions

P4Sync

Description:

Synchronize the current workspace with the depot.

Parameters

Attribute Description Required
force force a refresh of files, if this attribute has been set. no - if ommitted, it will be off, otherwise a refresh will be forced.
label sync client to label no

Examples

<p4sync label="nightlybuild-0.0123" force="foo"/>

<p4sync view="//depot/projects/projectfoo/main/src/..."/>


P4Change

Description:

Request a new changelist from the Perforce server. This task sets the ${p4.change} property which can then be passed to P4Submit, P4Edit, or P4Add.

Parameters

Attribute Description Required
description Description for ChangeList. If none specified, it will default to "AutoSubmit By Ant" No.

Examples

<p4change description="Change Build Number in Script">


P4Edit

Description:

Open file(s) for edit. P4Change should be used to obtain a new changelist for P4Edit as, although P4Edit can open files to the default change, P4Submit cannot yet submit it.

Parameters

Attribute Description Required
view The filespec to request to edit Yes
change An existing changelist number to assign files to. No, but see above.

Examples


<p4edit

    view="//depot/projects/projectfoo/main/src/Blah.java..."

    change="${p4.change}"/>


P4Submit

Description:

Submit a changelist, usually obtained from P4Change.

Parameters

Attribute Description Required
change The changelist number to submit Yes

Examples

<p4submit change="${p4.change}"/>


P4Have

Description:

List handy file info reflecting the current client contents.

Parameters

Attribute Description Required
None -- --

Examples

<p4have/>


P4Label

Description:

Create a new label and set contents to reflect current client file revisions.

Parameters

Attribute Description Required
name The name of the label Yes
view client view to use for label No
desc Label Description No
lock Lock the label once created. No

Examples


<p4label

	name="NightlyBuild:${DSTAMP}:${TSTAMP}" 

	desc="Auto Nightly Build"

	lock="locked"

/>


P4Counter

Description:

Obtain or set the value of a counter. When used in its base form (where only the counter name is provided), the counter value will be printed to the output stream. When the value is provided, the counter will be set to the value provided. When a property name is provided, the property will be filled with the value of the counter. You may not specify to both get and set the value of the counter in the same Task.

The user performing this task must have Perforce "review" permissions as defined by Perforce protections in order for this task to succeed.

Parameters

Attribute Description Required
name The name of the counter Yes
value The new value for the counter No
property The property to be set with the value of the counter No

Examples

Print the value of the counter named "last-clean-build" to the output stream:

<p4counter name="last-clean-build"/>

Set the value of the counter based on the value of the "TSTAMP" property:

<p4counter name="last-clean-build" value="${TSTAMP}"/>

Set the value of the "p4.last.clean.build" property to the current value of the "last-clean-build" counter:

<p4counter name="last-clean-build" property="${p4.last.clean.build}"/>


P4Reopen

Description:

Move (or reopen in Perforce speak) checkout files between changelists.

Parameters

Attribute Description Required
tochange The changelist to move files to. Yes

Examples

Move all open files to the default changelist

<p4reopen view="//..." tochange="default"/>

Create a new changelist then reopen into it, any files from the view //projects/foo/main/...

<p4change description="Move files out of the way"/>

<p4reopen view="//projects/foo/main/..." tochange="${p4.change}"/>


P4Revert

Description:

Reverts files.

Parameters

Attribute Description Required
change The changelist to revert. No
revertOnlyUnchanged Revert only unchanged files (p4 revert -a) No

Examples

Revert everything!

<p4revert view="//..."/>

Revert any unchanged files in the default change

<p4revert change="default" revertonlyunchanged="true"/>


P4Add

Description:

Adds files specified in nested fileset children.

Parameters

Attribute Description Required
commandlength A positive integer specifying the maximum length of the commandline when calling Perforce to add the files. Defaults to 450, higher values mean faster execution, but also possible failures. No
changelist If specified the open files are associated with the specified pending changelist number; otherwise the open files are associated with the default changelist. No

Examples

Require a changelist, add all java files starting from a directory, and submit

<p4change/>

<p4add commandlength="20000" changelist="${p4.change}">

    <fileset dir="../dir/src/" includes="**/*.java"/>

<p4add>

<p4submit change="${p4.change}"/>

Change History

Sept 2000 -- Internal Release within Rubus
Nov 2000 V1.0 Initial Release donated to ASF :-)
Jan 2001 V1.1 fixed cross platform (NT/Unix) bug
refactored p4 output handling code
refactored exec'ing code

Copyright © 2001-2002 Apache Software Foundation. All rights Reserved.