wangwei
/
antliscence
forked from youys/ant

<html>
<head>
<title>Perforce Tasks for ANT</title>
</head>
<body>
<h1>Perforce Tasks User Manual</h1>
<p>by</p>
<ul>
    <li>Les Hughes (<a href="mailto:leslie.hughes@rubus.com">leslie.hughes@rubus.com</a>)</li>
</ul>
<p>Version 1.1 - 2001/01/09</p>
<hr>
<h2>Contents</h2>
<ul>
    <li><a href="#intro">Introduction</a></li>
    <li><a href="#tasks">The Tasks</a></li>
    <li><a href="#changes">Change History</a></li>
</ul>
<br>
<h2><a name="intro">Introduction</a></h2>
<p>These tasks provide an interface to the <a href="http://www.perforce.com" target="_top">Perforce</a> SCM.
The <code>org.apache.tools.ant.taskdefs.optional.perforce</code> 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.</p>

<p><b>Note:</b> These tasks require the <a href="http://jakarta.apache.org/oro" target="_top">oro 2.0</a> 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.
</p>


<h2><a name="tasks">The Tasks</a></h2>

<table border="0" cellspacing="0" cellpadding="3">
    <tr>
        <td><a href="#p4sync">P4Sync</a></td>
        <td>Synchronise a workspce to a depot</td>
    </tr>
    <tr>
        <td><a href="#p4change">P4Change</a></td>
        <td>Request a new changelist from the perforce server</td>
    </tr>
    <tr>
        <td><a href="#p4edit">P4Edit</a></td>
        <td>Open files for edit (checkout)</td>
    </tr>
    <tr>
        <td><a href="#p4submit">P4Submit</a></td>
        <td>Submit a changelist to the perforce server (checkin)</td>
    </tr>
    <tr>
        <td><a href="#p4have">P4Have</a></td>
        <td>List current files in client view, useful for reporting</td>
    </tr>
    <tr>
        <td><a href="#p4label">P4Label</a></td>
        <td>Create a label reflecting files in the current workspace</td>
    </tr>
    <tr>
        <td><a href="#p4counter">P4Counter</a></td>
        <td>Obtain or set the value of a counter</td>
    </tr>
</table>

<h3>General P4 Properties</h3>
<p>Each p4 task requires a number of settings, either through build-wide properties, individual attributes 
or environment variables. These are
</p>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Property</b></td>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Env Var</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Default</b></td>
  </tr>
  <tr>
    <td valign="top">p4.port</td>
    <td valign="top">port</td>
    <td valign="top">P4PORT</td>
    <td valign="top">The p4d server and port to connect to</td>
    <td valign="top">perforce:1666</td>
  </tr>
  <tr>
    <td valign="top">p4.client</td>
    <td valign="top">client</td>
    <td valign="top">P4CLIENT</td>
    <td valign="top">The p4 client spec to use</td>
    <td valign="top">The logged in username</td>
  </tr>
  <tr>
    <td valign="top">p4.user</td>
    <td valign="top">user</td>
    <td valign="top">P4USER</td>
    <td valign="top">The p4 username</td>
    <td valign="top">The logged in username</td>
  </tr>
<tr>
    <td valign="top" align="center">--</td>
    <td valign="top">view</td>
    <td valign="top" align="center">--</td>
    <td valign="top">The client, branch or label view to operate upon. See the p4 user guide for more info.</td>
    <td valign="top">//...</td>
  </tr>

</table>
<p>
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.
</p>

<h3>Examples</h3>
<p>Setting in the environment:-</p>
<p>
(Unix csh)</p>
<pre>setenv P4PORT myperforcebox:1666</pre>
<p>(Unix sh et al)</p>
<pre>P4USER=myp4userid; export P4USER</pre>
<p>Using build properties:-</p>
<pre>&lt;property name=&quot;p4.client&quot; value=&quot;nightlybuild&quot;/&gt;</pre>
<p>Using task attributes:-</p>
<pre>
&lt;p4Whatever
	port=&quot;myserver:1666&quot;
	client=&quot;smoketest&quot;
	user=&quot;smoketestdude&quot;
	.
	.
	.
/&gt;
</pre>

<p>
For more information regarding the underlying 'p4' commands you are referred to the Perforce Command Reference
available from the <a href="http://www.perforce.com/" target="_top">Perforce website</a>.
</p>

<h3>Taskdefs</h3>
<p>Standard taskdefs (for you to copy'n'paste)</p>
<pre>
    &lt;taskdef name=&quot;p4sync&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Sync&quot; /&gt;
    &lt;taskdef name=&quot;p4change&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Change&quot; /&gt;
    &lt;taskdef name=&quot;p4edit&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Edit&quot; /&gt;
    &lt;taskdef name=&quot;p4submit&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Submit&quot; /&gt;
    &lt;taskdef name=&quot;p4have&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Have&quot; /&gt;
    &lt;taskdef name=&quot;p4label&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Label&quot; /&gt;
    &lt;taskdef name=&quot;p4counter&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Counter&quot; /&gt;
</pre>

<hr>
<h2>Task Descriptions</h2>
<h2><a name="p4sync">P4Sync</a></h2>
<h3>Description:</h3>
<p>Synchronize the current workspace with the depot.</p>

<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">force</td>
    <td valign="top">force a refresh of files</td>
    <td valign="top" align="center">no</td>
  </tr>
<tr>
    <td valign="top">label</td>
    <td valign="top">sync client to label</td>
    <td valign="top" align="center">no</td>
  </tr>
</table>

<h3>Examples</h3>
<pre>&lt;p4sync label=&quot;nightlybuild-0.0123&quot; force=&quot;yes&quot; /&gt;
&lt;p4sync view=&quot;//depot/projects/projectfoo/main/src/...&quot; /&gt;
</pre>
<hr>


<h2><a name="p4change">P4Change</a></h2>
<h3>Description:</h3>
<p>Request a new changelist from the perforce server. 
This task sets the ${p4.change} property which can then be passed to P4Submit or P4Edit.
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">description</td>
    <td valign="top">Description for ChangeList. If none specified, it will
                     default to "AutoSubmit By Ant"</td>
    <td valign="top" align="center">No.</td>
  </tr>
</table>

<h3>Examples</h3>
<pre>&lt;p4change description="Change Build Number in Script"&gt;
</pre>
<hr>


<h2><a name="p4edit">P4Edit</a></h2>
<h3>Description:</h3>
<p>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.
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">view</td>
    <td valign="top">The filespec to request to edit</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">change</td>
    <td valign="top">An existing changelist number to assign files to.</td>
    <td valign="top" align="center">No, but see above.</td>
  </tr>

</table>

<h3>Examples</h3>
<pre>
&lt;p4edit
	view=&quot;//depot/projects/projectfoo/main/src/Blah.java...&quot;
	change=&quot;${p4.change}&quot; /&gt;
</pre>
<hr>


<h2><a name="p4submit">P4Submit</a></h2>
<h3>Description:</h3>
<p>Submit a changelist, usually obtained from P4Change.
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">change</td>
    <td valign="top">The changelist number to submit</td>
    <td valign="top" align="center">Yes</td>
  </tr>
</table>

<h3>Examples</h3>
<pre>&lt;p4submit change=&quot;${p4.change}&quot; /&gt;
</pre>
<hr>


<h2><a name="p4have">P4Have</a></h2>
<h3>Description:</h3>
<p>List handy file info reflecting the current client contents.
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">None</td>
    <td valign="top" align="center">--</td>
    <td valign="top" align="center">--</td>
  </tr>
</table>

<h3>Examples</h3>
<pre>&lt;p4have /&gt;
</pre>
<hr>


<h2><a name="p4label">P4Label</a></h2>
<h3>Description:</h3>
<p>Create a new label and set contents to reflect current client file revisions.
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">The name of the label</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">view</td>
    <td valign="top">client view to use for label</td>
    <td valign="top" align="center">No</td>
  </tr>
  <tr>
    <td valign="top">desc</td>
    <td valign="top">Label Description</td>
    <td valign="top" align="center">No</td>
  </tr>


</table>
<h3>Examples</h3>
<pre>
&lt;p4label
	name=&quot;NightlyBuild:${DSTAMP}:${TSTAMP}&quot; 
	desc=&quot;Auto Nightly Build&quot;
/&gt;
</pre>
<hr>


<h2><a name="p4counter">P4Counter</a></h2>
<h3>Description:</h3>
<p>Obtain or set the value of a counter
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">The name of the counter</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">value</td>
    <td valign="top">The new value for the counter</td>
    <td valign="top" align="center">No</td>
  </tr>
</table>

<h3>Examples</h3>
<pre>
&lt;p4counter name=&quot;last-clean-build&quot; /&gt;
&lt;p4counter name=&quot;last-clean-build&quot; value=&quot;${TSTAMP}&quot; /&gt;
</pre>
<hr>


<h2><a name="changes">Change History</a></h2>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
    <td valign="top">Sept 2000</td>
    <td valign="top" align="center">--</td>
    <td valign="top">Internal Release within Rubus</td>
</tr>

<tr>
    <td valign="top">Nov 2000</td>
    <td valign="top">V1.0</td>
    <td valign="top">Initial Release donated to ASF :-)</td>
</tr>
<tr>
    <td valign="top">Jan 2001</td>
    <td valign="top">V1.1</td>
    <td valign="top">fixed cross platform (NT/Unix) bug<br>refactored p4 output handling code<br>refactored exec'ing code</td>
</tr>
</table>
</body>
</html>