Perforce Tasks User Manual

Les Hughes (leslie.hughes@rubus.com)
Kirk Wylie (kirk@radik.com)
Matt Bishop (matt@thebishops.org)
Antoine Levy-Lambert

Introduction
The Tasks
Change History

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
P4Labelsync	Syncs an existing label
P4Counter	Obtain or set the value of a counter
P4Reopen	Move files between changelists
P4Revert	Revert files
P4Add	Add files
P4Delete	Delete files
P4Integrate	Integrate files
P4Resolve	Resolve files
P4Fstat	Show differences between local repository and p4 repository

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). Many of these settings can be set using the globalopts attribute (described below), but not all. If a setting cannot be set by the command-line options, then it can only be set outside of Ant as an environment variable.

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.

globalopts
Specifies global options for perforce to use while executing the task. These properties should be concatenated into one string,
such as "-P password -C EUCJIS". Use the command-line option syntax, NOT the environment variable names. See the
Perforce Command Reference for details. No

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.

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, or P4Delete, then to P4Submit.

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.

P4Submit will also change the value of the property p4.change if the change list is renamed by the Perforce server.

P4Submit will set a property p4.needsresolve to 1 if the change could not be submitted due to files needing resolving.

Files will need resolve if at the time of checking in, the revision that was checked out to do the current edit is not the latest any more.

If no files need resolve, the p4.needsresolve will be set to 0.

Parameters

Attribute	Description	Required
change	The changelist number to submit	Yes
changeproperty	Name of a property to which the new change number will be assigned if the Perforce server renumbers the change Since ant 1.6.1	No
needsresolveproperty	Name of property which will be set to `true` if the submit requires a resolve Since ant 1.6.1	No

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 The view can contain multiple lines separated by ; or :	No
desc	Label Description	No
lock	Lock the label once created.	No

Examples

<p4label
	name="NightlyBuild:${DSTAMP}:${TSTAMP}"
	desc="Auto Nightly Build"
	lock="locked"
	label="//firstdepot/...;//secondepot/foo/bar/..."
/>

P4Labelsync

Description:

Syncs an existing label against the current workspace or against specified revisions.

Parameters

Attribute	Description	Required	Perforce command line flag
name	The name of the label	Yes	-l labelname
view	list of files or revision specs separated by : or ; in the absence of this attribute, the labelsync will be done against the current Perforce client or the value of the p4client attribute or the value of the p4.client property or the value of the environment variable P4CLIENT	No	file[revRange] ...
simulationmode	Displays which effect the operation would have on the label but do not actually do it	No	-n
add	If set to true, preserve files which exist in the label, but not in the current view	No	-a
delete	If set to true, remove from the label the files mentioned in the view attribute	No	-d

Examples

<
p4labelsync
name="current_release"
view="//depot/...#head;//depot2/file1#25"
add="true"
/>

This example will add into the label called current_release the current head revision of all the files located under //depot and the revision 25 of the file //depot2/file1.

<
p4labelsync
name="current_release"
p4client="myclient"
/>

This example will update the label called current_release so that it reflects the Perforce client myclient.
Files present in the label before the sync and not present currently in the client will be removed from the label, because the add attribute is not set.

<
p4labelsync
name="current_release"
/>

This example will update the label called current_release so that it reflects the current default client for the ant Perforce tasks.
The default client is by order of priority :

the value of the p4.client property if set in the project
the value of the P4CLIENT environment variable
the default Perforce client from the Windows registry under Windows operating systems

Files present in the label before the sync and not present currently in the client will be removed from the label, because the add attribute is not set.

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}"/>

P4Fstat

Description:

Lists files under Perforce control and files not under Perforce control in one or several filesets

Parameters

Attribute

Description

Required

showfilter

should be one of

value	description
"all"	list all files, first the ones which are under Perforce control, then the others
"existing"	list only files under Perforce control
"non-existing"	list only files which are not under Perforce control

Yes

fileset

one or several fileset(s)

yes (at least one fileset is needed)

Several nested filesets can be used with P4Fstat, one should be there at least.

Examples

will list all the files under C:\dev\gnu\depot, sorted by under Perforce or not under Perforce

<project name="p4fstat" default="p4fstat" basedir="C:\dev\gnu">
    <target name="p4fstat" >
        <p4fstat showfilter="all">
            <fileset dir="depot" includes="**/*"/>
        </p4fstat>
    </target>
</project>

P4Delete

Description:

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

Parameters

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

Examples

<p4delete
    view="//depot/projects/projectfoo/main/src/Blah.java..."
    change="${p4.change}"/>

P4Integrate

Description:

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

Parameters

If this task is used without using a branch definition, both fromfile and tofile must be supplied. If a branch definition is supplied, at least one of fromfile or tofile should be supplied. Both fromfile and tofile can be supplied together with a branch definition.

Attribute	Description	Required	Perforce command line flag
fromfile	Original file or view	required if a branch is not specified
tofile	Target file or view.	required if a branch is not specified
branch	Name of branch specification	No	-b
change	An existing changelist number to assign files to.	No, but see above.	-c
forceintegrate	Forces integration regardless of previous integration history (*)	No	-f
restoredeletedrevisions	Enables integration around deleted revisions (*)	No	-d
leavetargetrevision	Prevents target files from being synced to head revision before integration (*)	No	-h
enablebaselessmerges	Forces integration to existing target files which have no integration history relative to the source files (*)	No	-i
simulationmode	Displays which integrations are necessary but do not actually schedule them (*)	No	-n
reversebranchmappings	Reverses mappings in the branch view, with source and target files exchanging place (*)	No	-r
propagatesourcefiletype	Makes source file type propagate to existing target files (*)	No	-t
nocopytargetfiles	Prevents the physical delivery on disk of new target files (*)	No	-v

(*) The following applies for a number of flags. The default is false. To set the flag, use "true"

Examples

<p4integrate
    fromfile="//depot/projects/projectfoo/main/src/Blah.java..."
    tofile="//depot/projects/projectfoo/release/src/Blah.java..."
    change="${p4.change}"/>

P4Resolve

Description:

Resolves files. You want to do this if :

there have been or there may be concurrent edits of the same file. For instance, you have begun to edit a file, and while you were working on it, somebody has submitted a new version of the same file. When you first attempt to submit your file(s), you will get a message (property p4.needsresolve set).
you have just been doing an integration to existing target files

P4Resolve does not use a change list number (it takes it from the files it is working on).

Parameters

Attribute	Description	Required	Perforce command line flag
view	The filespec to request to delete	Yes
resolvemode	Should have one of these values : "automatic" "force" "safe" "theirs" "yours"	Yes	corresponds to one of -am -af -as -at -ay
redoall	allows previously resolved files to be resolved again (*)	No	-f
simulationmode	Lists the integrations which would be performed, without actually doing them. (*)	No	-n
forcetextmode	Attempts a textual merge, even for binary files (*)	No	-t
markersforall	Puts in markers for all changes, conflicting or not (*)	No	-v

(*) The following applies for a number of flags. The default is false. To set the flag, use "true"

Examples

<p4resolve
    view="//depot/projects/projectfoo/main/src/Blah.java..."
    resolvemode="automatic"/>

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
Jan 2003	V1.2	Added globalopts to P4Base to allow additional global options to be set. Added p4fstat task
May 2003	V1.3	Added p4labelsync, p4resolve, p4integrate. Changed p4submit (detection of changes of change numbers, and of failed submits due to resolution needed)
Jan 2004	ant 1.6.1	Changed p4submit, needsresolveproperty and changeproperty added

Perforce Tasks User Manual

Contents

General P4 Properties

Examples

Task Descriptions

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples

Description:

Parameters

Examples