| <html> |
| <head> |
| <title>Perforce Tasks</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> |
| <li>Kirk Wylie (<a href="mailto:kirk@radik.com">kirk@radik.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.XXX</a> 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. |
| </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 workspace 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> |
| <tr> |
| <td><a href="#p4reopen">P4Reopen</a></td> |
| <td>Move files between changelists</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#p4revert">P4Revert</a></td> |
| <td>Revert files</td> |
| </tr> |
| |
| <tr> |
| <td><a href="#p4add">P4Add</a></td> |
| <td>Add files</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><property name="p4.client" value="nightlybuild"/></pre> |
| <p>Using task attributes:-</p> |
| <pre> |
| <p4Whatever |
| port="myserver:1666" |
| client="smoketest" |
| user="smoketestdude" |
| . |
| . |
| . |
| /> |
| </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) -- normally this is done automatically if you install this optional task.</p> |
| <pre> |
| <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" /> |
| </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><p4sync label="nightlybuild-0.0123" force="yes" /> |
| <p4sync view="//depot/projects/projectfoo/main/src/..." /> |
| </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 <A HREF="#p4submit">P4Submit</A>, |
| <A HREF="#p4edit">P4Edit</A>, or <a HREF="#p4add">P4Add</A>. |
| </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><p4change description="Change Build Number in Script"> |
| </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> |
| <p4edit |
| view="//depot/projects/projectfoo/main/src/Blah.java..." |
| change="${p4.change}" /> |
| </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><p4submit change="${p4.change}" /> |
| </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><p4have /> |
| </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> |
| <tr> |
| <td valign="top">lock</td> |
| <td valign="top">Lock the label once created.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| |
| |
| </table> |
| <h3>Examples</h3> |
| <pre> |
| <p4label |
| name="NightlyBuild:${DSTAMP}:${TSTAMP}" |
| desc="Auto Nightly Build" |
| lock="locked" |
| /> |
| </pre> |
| <hr> |
| |
| |
| <h2><a name="p4counter">P4Counter</a></h2> |
| <h3>Description:</h3> |
| <p> |
| 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. |
| </p> |
| <P> |
| The user performing this task must have Perforce "review" permissions |
| as defined by Perforce protections in order for this task to succeed. |
| </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> |
| <tr> |
| <td valign="top">property</td> |
| <td valign="top">The property to be set with the value of the counter</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| Print the value of the counter named "last-clean-build" to the output stream: |
| <pre> |
| <p4counter name="last-clean-build" /> |
| </PRE> |
| Set the value of the counter based on the value of the "TSTAMP" property: |
| <PRE> |
| <p4counter name="last-clean-build" value="${TSTAMP}" /> |
| </PRE> |
| Set the value of the "p4.last.clean.build" property to the current |
| value of the "last-clean-build" counter: |
| <PRE> |
| <p4counter name="last-clean-build" property="${p4.last.clean.build}" /> |
| </pre> |
| <hr> |
| |
| |
| |
| |
| <h2><a name="p4reopen">P4Reopen</a></h2> |
| <h3>Description:</h3> |
| <p> |
| Move (or reopen in Perforce speak) checkout files between changelists. |
| </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">tochange</td> |
| <td valign="top">The changelist to move files to.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| Move all open files to the default changelist |
| <pre> |
| <p4reopen view="//..." tochange="default" /> |
| </PRE> |
| Create a new changelist then reopen into it, any files from the view //projects/foo/main/... |
| <PRE> |
| <p4change description="Move files out of the way" /> |
| <p4reopen view="//projects/foo/main/..." tochange="${p4.change}" /> |
| </pre> |
| <hr> |
| |
| |
| |
| <h2><a name="p4revert">P4Revert</a></h2> |
| <h3>Description:</h3> |
| <p> |
| Reverts files. |
| </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 to revert.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">revertOnlyUnchanged</td> |
| <td valign="top">Revert only unchanged files (p4 revert -a)</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| |
| </table> |
| |
| <h3>Examples</h3> |
| Revert everything! |
| <pre> |
| <p4revert view="//..." /> |
| </PRE> |
| Revert any unchanged files in the default change |
| <PRE> |
| <p4revert change="default" revertonlyunchanged="true" /> |
| </pre> |
| <hr> |
| |
| <h2><a name="p4add">P4Add</a></h2> |
| <h3>Description:</h3> |
| <p> |
| Adds files specified in nested fileset children. |
| </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">commandlength</td> |
| <td valign="top">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.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">changelist</td> |
| <td valign="top">If specified the open files are associated with the |
| specified pending changelist number; otherwise the open files are |
| associated with the default changelist.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| |
| </table> |
| |
| <h3>Examples</h3> |
| Require a changelist, add all java files starting from a directory, |
| and submit |
| |
| <pre> |
| <p4change/> |
| <p4add commandlength="20000" changelist="${p4.change}"> |
| <fileset dir="../dir/src/" includes="**/*.java"/> |
| <p4add> |
| <p4submit change="${p4.change}"/> |
| </pre> |
| |
| <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> |
| <hr> |
| <p align="center">Copyright © 2001 Apache Software Foundation. All rights |
| Reserved.</p> |
| </body> |
| </html> |