# Perforce Tasks User Manual

by

- Les Hughes (leslie.hughes@rubus.com)

Version 1.1 - 2001/01/09

## 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 2.0 regular expression package. Simply download this package and copy the jakarta-oro-2.0.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 workspce 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

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

### 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)

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

## Task Descriptions

## P4Sync

### Description:

Synchronize the current workspace with the depot.

### Parameters

Attribute | Description | Required
force | force a refresh of files | no
label | sync client to label | no

### Examples

    <p4sync label="nightlybuild-0.0123" force="yes" />
    <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 or P4Edit.

### 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

### Examples

    <p4label
    	name="NightlyBuild:${DSTAMP}:${TSTAMP}"
    	desc="Auto Nightly Build"
    />

## 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