Perforce Tasks User Manual

by

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

Contents

• 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 regular expression package. See library dependencies for the precise version required. You will also need the Perforce client executable (p4 or p4.exe but not p4win.exe) in your path.

The Tasks

General P4 Properties

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

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

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

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

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

Examples

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

P4Have

Description:

List handy file info reflecting the current client contents.

Parameters

Examples

<p4have/>

P4Label

Description:

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

Parameters

Examples

<p4label
	name="NightlyBuild:20061213:0714" 
	desc="Auto Nightly Build"
	lock="locked"
	view="//firstdepot/...;//secondepot/foo/bar/..."
/>

P4Labelsync

Description:

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

Parameters

Examples

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

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

<
p4labelsync
name="current_release"
/>

• 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

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

Examples

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

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

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

P4Reopen

Description:

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

Parameters

Examples

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

<p4change description="Move files out of the way"/>
<p4reopen view="//projects/foo/main/..." tochange="${p4.change}"/>

P4Revert

Description:

Reverts files.

Parameters

Examples

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

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

P4Add

Description:

Adds files specified in nested fileset children.

Parameters

Examples

<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

Examples

<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

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.

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

Parameters

Examples

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

Change History