Release Notes for
P4Perl, the Perl interface to the Perforce SCM System
Version 2009.1
Introduction
This document lists all user-visible changes to P4Perl
from release 2007.3, the first supported P4Perl release.
Perforce numbers releases YYYY.R/CCCCC, e.g. 2002.1/30547.
YYYY is the year; R is the release of that year; CCCCC is the
bug fix change level. Each bug fix in these release notes is
marked by its change number. Any build includes (1) all bug fixes
of all previous releases and (2) all bug fixes of the current
release up to the bug fix change level.
To determine the version of your P4Perl, issue the following
command:
perl -MP4 -e "print P4::Identify()"
--------------------------------------------------------------------------
Installing P4Perl
Windows users can download an installer containing pre-built packages
for P4Perl from the Perforce FTP site. Users on other platforms must
build from source, as detailed below.
--------------------------------------------------------------------------
Building P4Perl from Source
1. Download a suitable Perforce C++ API build from the Perforce FTP
site at "ftp.perforce.com/perforce". There is typically only one
option per platform. Exceptions:
- OS X: get the universal binary version of the API
in the "bin.darwin*u" directory.
- Windows: get "p4api_vs2003_static.zip" in the
"bin.ntx86" directory.
2. Extract the API archive into an empty directory.
3. Issue the following commands:
perl Makefile.PL --apidir
UNIX: make
Windows: nmake
To reinstall cleanly, remove the directory created in step 2,
then re-extract the archive. After the build has finished,
run the test script to verify that the build succeeded:
UNIX: make test
Windows: nmake test
NOTE: The test harness requires the Perforce server executable
p4d to be installed and in the PATH.
4. To install P4Perl, run the following command. On UNIX systems,
this step must be run as root:
UNIX (must be root): make install
Windows: nmake install
--------------------------------------------------------------------------
Compatibility Statements
Server Compatibility
You can use any release of P4Perl with any release of the
Perforce server later than 2001.1
API Compatibility
The 2009.1 release of P4Perl supports the 2009.1 Perforce API. Older
releases (down to 2008.2) might work but are not supported.
Perl compatibility
The 2009.1 release of P4Perl is compatible with Perl 5.8 and Perl 5.10
when built from source. The build included in the Windows installer is
compatible with ActivePerl 5.8.8 build 822.
Platform compatibility
While P4Perl is generally portable, this release is certified only on
the following platforms:
Linux
Solaris
Windows
FreeBSD
Max OSX (10.4 and later)
Compiler Compatibility
To build P4Perl from source, you must use a version of Perl that
has been compiled with the same compiler used to build the Perforce C++
API. For most platforms, use gcc/g++.
Attempting to use a different compiler or a different version
of the compiler can cause linker errors due to differences in name
handling between compilers.
On Windows platforms, Visual Studio 2003 must be used to compile
P4Perl. Most Windows users can use the Windows installer available
from the Perforce web site.
Compatibility with Previous Releases
P4Perl 2009.1 is backwards-compatible with all previous releases from
Perforce Software.
Compatibility with P4Perl from the Public Depot
Perforce P4Perl is significantly different from the version
of P4Perl available from the Perforce Public Depot. There have been
numerous improvements, and several interface changes intended
to make P4Perl consistent with the other scripting
interfaces.
If you are migrating from the Public Depot version of P4Perl,
edit your scripts to ensure that they comply with the new
interface. The differences are detailed below.
Deleted Methods
---------------
The following methods have been deleted from the P4 class and
are no longer available.
Dropped() Use IsConnected()
Final() Use Disconnect()
Init() Use Connect()
IsParseForms() Form parsing is now always on
Login() Use RunLogin()
MergeErrors() Errors and warnings are now separate
ParseForms() Form parsing is now always on
Tag() Tagged mode is on by default [see Tagged()]
New Methods
-----------
The following methods are new to P4Perl.
GetApiLevel() Returns the API compatibility level
P4ConfigFile() Returns the path of the P4CONFIG file
IsConnected() Returns true if the client is connected
Debug() Sets the debug level
GetMaxResults() Returns the current maxresults limit
GetMaxScanRows() Returns the current maxscanrows limit
GetMaxLockTime() Returns the current maxlocktime limit
SetMaxLockTime() Sets the current maxlocktime limit
GetProg() Returns the name of the program (if set)
ServerLevel() Returns the (numeric) level of the server
GetTicketFile() Returns the path to the current ticket file
SetTicketFile() Sets the path to the current ticket file
GetVersion() Returns the version of the script
SetVersion() Sets the version of the script
Renamed Methods
---------------
In the Public Depot version of P4Perl, unknown methods are assumed to
be Perforce command and are executed accordingly. For example, you can
issue a "p4 info" command as follows:
$p4->Info();
This approach causes problems with keywords like
"client," which is both a command and a setting in the
client environment (P4CLIENT). To resolve this ambiguity
and to make P4Perl consistent with other Perforce
scripting interfaces, this convention has been changed.
In Perforce P4Perl, methods with names prefixed with
"Run" are interpreted as Perforce commands. For example:
$p4->RunInfo();
Tagged Mode and Form Parsing
----------------------------
In the Public Depot version of P4Perl, tagged output and
form parsing mode are off by default but most scripts
turn them on immediately. In Perforce P4Perl, both form
parsing and tagged output are on by default.
Form parsing cannot be explicitly disabled, but tagged output may
be turned on and off by using the following calls:
$p4->Tagged( 0 ); # Disabled
$p4->Tagged( 1 ); # Enabled
Because form parsing does not work when tagged output is disabled,
this method can be used to disable form parsing.
Calling Tagged() without a parameter is no longer supported.
Most users can simply delete any old calls to Tagged()
from their scripts. Previously it was not possible to
disable tagged output after enabling it.
--------------------------------------------------------------------------
Key to symbols used in change notes below.
* -- requires new P4Perl
** -- requires P4Perl built with new P4API
*** -- requires new p4d server program
--------------------------------------------------------------------------
Major new functionality in 2009.1
#193914 (Bug #26730) *
The P4::Tagged() method now accepts an optional code reference
as well as a boolean, which enables you to run a subroutine with
the tagged status of the session temporarily toggled. For
example:
my $GetChangeCounter = sub{ $p4->RunCounter('change')->[ 0 ] };
my $changeno = $p4->Tagged( 0, $GetChangeCounter );
#191642 *
The P4::Spec class has a new method, PermittedFields,
which lists the field names that are permitted in specs of
that type.
Bugs fixed in 2009.1
#192044 (Bug #30071) *
P4::RunLogin() now supports all valid arguments to "p4 login".
#192043 (Bug# 32966) *
P4::RunPassword() can now handle the case when the user has
not previously set a password. For old password, specify an empty string.
For example:
$p4->RunPassword( $p4->GetPassword(), "newpassword" );
work regardless of whether a current password is set.
#192035 (Bug# 31437) *
P4Perl now builds correctly when the API directory is
specified using a relative path.
#191643 (Bug #28646) *
P4Perl now correctly parses jobs when the jobspec contained a
field with a name ending in a number.
--------------------------------------------------------------------------
New functionality in 2008.2
#165187 (Bug #30362) *
A new class, P4::Map, exposes the Perforce mapping logic to
P4Perl users. This class enables script writers
to create and manipulate Perforce mappings within scripts.
The following methods are available in the P4::Map class:
Class Methods:
new() Constructor
Join() Join two maps returning a third
Instance Methods:
Clear() Empty a map
Count() Return the number of entries
IsEmpty() Tests whether a map object is empty
Insert() Inserts an entry into the map
Includes() Tests whether a path is mapped
Reverse() Swap left and right sides of the mapping
Translate() Translate a string through a map
Lhs() Returns the left side as an array
rhs() Returns the right side as an array
AsArray() Returns the map as an array
Bugs fixed in 2008.2
#169807 (Bug #31110) *
P4Perl no longer crashes when RunResolve() is passed a P4::Resolver
object and a file path.
--------------------------------------------------------------------------
New functionality in 2008.1
#158238 (Bug #27433) *
P4::RunResolve() now supports interactive resolves through two
new classes: P4::Resolver, and P4::MergeData. P4::Resolver is
a base class intended to be subclassed by users; simply
override the Resolve() method to implement the required merge
behavior. P4::Resolver::Resolve() is passed a P4::MergeData
object when it is called; this object contains the information
about the names and locations of the files in the merge, and
the hint from Perforce's built-in merge algorithm.
#152357 (Bug #25063) *
The 'P4::GetEnv( $var )' method has been added to the
P4 class. This instance method enables the caller to interrogate
the Perforce environment, including reading Perforce variables
from P4CONFIG files and, on Windows, the registry. P4::SetCwd()
now loads any P4CONFIG file settings that are appropriate to
the new working directory.
#151525 *
P4Perl now returns P4::Spec objects from all methods
that parse Perforce forms. A P4::Spec object is a
blessed hash reference, so most existing code is
unaffected. Code that iterates over all members of
the hash must skip the new '_fields_' member. This
member variable is used to store a list of field names
that are valid in forms of that type. This approach
enables accessor methods for the fields in the form.
Simply call a method with the name of the field you
want to get or set prefixed with an underscore (_).
For example:
$client->_Root(); # Get client root
$client->_Root( $newroot ); # Set client root
Updating the hash directly is still supported and is
equivalent to using the method-based interface.
#158308 (Bug #29309) *
P4Perl now supports Mac OS X 10.5.
Bugs fixed in 2008.1
#158323 (Bug #29953) *
The P4::GetApiLevel() was missing; it has now been
implemented.
#150578 (Bug #28760) *
The presence of deleted revisions in a file's history
might cause the fileSize and digest attributes to be
incorrect for other revisions in the output of
P4::RunFilelog(). This problem occurred because a
digest and file size were allocated to the deleted
revision. This problem has been corrected.