Release Notes for P4Perl, the Perl interface to the Perforce SCM System GA Release 2008.2 September 30, 2008 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 bugfix change level. Each bugfix in these release notes is marked by its change number. Any build includes (1) all bugfixes of all previous releases and (2) all bugfixes of the current release up to the bugfix change level. To determine the version of your P4Perl, run the following command: perl -MP4 -e "print P4::Identify()" Installing P4Perl Windows users can download an installer for P4Perl from the Perforce FTP site. Users on other platforms must build from source. Building P4Perl from Source 1. Download a suitable Perforce API build from the Perforce FTP site 2. Extract the API tarfile into an empty directory 3. Run the following commands: perl Makefile.PL --apidir make (on Unix) nmake (on Windows) make test (on Unix) nmake test (on Windows) NOTE: The test harness requires that 'p4d' be installed and in the PATH 4. To install P4Perl, run the following command. On Unix systems, this step should be run as root: make install (on Unix) nmake install (on Windows) Compatibility Statements 1. Server Compatibility Unless stated otherwise you can intermix any release of P4Perl with any release of the Perforce server later than 2001.1 2. API Compatibility The 2008.2 release of P4Perl supports the 2008.2 Perforce API. Older releases (down to 2006.2) may also work, but they are not supported. 3. Perl compatibility The 2008.2 release of P4Perl is compatible with Perl 5.8 when built from source. The build included in the Windows installer is compatible with ActivePerl 5.8.8 build 822. 4. 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) 5. 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, this means gcc/g++. Attempting to use a different compiler or a different version of the compiler will probably result in 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 will want to use the Windows Installer available from the Perforce website. 6. Compatibility with Previous Releases Unless otherwise stated in the notes below, P4Perl 2008.2 is backwards compatible with all previous releases from Perforce Software. 7. Compatibility with P4Perl from the Public Depot Perforce P4Perl is significantly different from the P4Perl in the Perforce Public Depot. There have been numerous improvments, and several interface changes intended to make P4Perl consistent with the other scripting interfaces. Users migrating from Public Depot Perl will need to edit their scripts in order to ensure that they comply with the new interface. For convenience, 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 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 Perforce 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 Public Depot P4Perl, any method that was not known, was assumed to be a Perforce command and executed accordingly. Thus, one could run a 'p4 info' by calling: $p4->Info(); This caused problems with nouns 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 taken to be Perforce commands, thus the example above becomes: $p4->RunInfo(); Tagged Mode and Form Parsing In Public Depot P4Perl, tagged output and form parsing mode were off by default, but most scripts turned 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 at will by using: $p4->Tagged( 0 ); # Disabled $p4->Tagged( 1 ); # Enabled Since form parsing does not work when tagged output is disabled, this method can be used to disable form parsing if necessary. Note that calling Tagged(), without a parameter is no longer valid. Most users can simply delete any old calls to Tagged() from their scripts as previously it was not possible to disable tagged output once enabled. Key to symbols used in change notes below. * -- requires new P4Perl ** -- requires P4Perl built with new P4API *** -- requires new p4d server program -------------------------------------------------------------------------------- Release 2008.2 New Funtionality in 2008.2 # 165187 * A new class, P4::Map has been added that exposes the Perforce mapping logic to P4Perl users. This class allows 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 (SIR#30362) -------------------------------------------------------------------------------- Release 2008.1 New Funtionality in 2008.1 # 158238 * 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 behaviour. 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. (SIR#27433) # 152357 * A new method 'P4::GetEnv( $var )' method has been added to the P4 class. This instance method allows 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. (SIR #25063) # 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 will be unaffected. Code that iterates over all members of the hash should skip the new '_fields_' member; this member variable is used to store a list of fieldnames that are valid in forms of that type. This, in turn, enables accessor methods for the fields in the form. Simply call a method with the name of the field you wish to get/set prefixed with an underscore (_). For example: $client->_Root(); # Get client root $client->_Root( $newroot ); # Set client root Updating the hash directly is still available, and is equivalent to using the method based interface. Bugs fixed in 2008.1 # 158323 * The P4::GetApiLevel() was missing; it has now been implemented. (BUG#29953) -------------------------------------------------------------------------------- Bugs Fixed since first release (2007.3/147242) #150578 * The presence of deleted revisions in a file's history could lead to the fileSize, and digest attributes being incorrect for other revisions in the output of P4::RunFilelog(). This occurred because a digest and filesize were allocated to the deleted revision. This problem has been corrected. (Bug #28760)