Release Notes for P4Perl, Perforce's script API for Perl Version 2012.2 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 at ftp://ftp.perforce.com/perforce. Users on other platforms must build from source, as detailed below. -------------------------------------------------------------------------- Building P4Perl from Source 1. Download the Perforce C++ API from the Perforce FTP site at "ftp://ftp.perforce.com/perforce". The API archive is located in release and platform-specific subdirectories and is named "p4api.tgz" for non-Windows platforms and "p4api_vs2008_static.zip" for Windows. Mac OS X users should get the API from either the "bin.darwin90x86" or "bin.darwin90x86_64" platform directory. Note: 32-bit builds of P4Perl require a 32-bit version of the C++ API and a 32-bit version of Perl. 64-bit builds of P4Perl require a 64-bit version of the C++ API and a 64-bit version of Perl. Unzip the archive into an empty directory. 2. Extract the P4Perl API archive into an empty directory. 3. To build P4Perl, run the following commands: perl Makefile.PL --apidir make (on Unix/Mac platforms) nmake (on Windows platforms) Note: to reinstall cleanly P4Perl, remove the directory created in step 2, then re-extract the archive. 4. To test your P4Perl build, run the following command: make test (on Unix/Mac platforms) nmake test (on Windows platforms) Note: on certain Windows platforms and versions of Perl, the manifest file is not automatically applied to P4.dll, so it must be done manually. This is known to happen on 32-bit Perl 5.8.x and 64-bit Perl 5.8.9. Tests failing with "Can't load ... P4.dll" are a symptom of this. The two commands to run are: mt -nologo -manifest blib\arch\auto\P4\P4.dll.manifest \ -outputresource:blib\arch\auto\P4\P4.dll;2 del blib\arch\auto\P4\P4.dll.manifest Note: the test harness requires the Perforce server executable p4d and Perforce command line executable p4 to be installed and in the PATH. 5. To install P4Perl, run the following command: make install (on Unix/Mac platforms) nmake install (on Windows platforms) Note: on Unix/Mac platforms, the installation must be performed as the root user SSL support ----------- Perforce Server 2012.1 and later supports SSL connections and the C++ API has been compiled with this support. For applications that do not require SSL support the C++ API provides a stub library (libp4sslstub.*) to satisfy the linker requirements. P4Perl will build with the stub library by default. To enable SSL support, provide the switch --ssl [librarypath] to the build. Without [librarypath] the linker will use the default ssl libraries provided by the operating system. If a library path is provided, the linker will be instructed to look there first. -------------------------------------------------------------------------- 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 2012.2 release of P4Perl supports the 2012.2 Perforce API. Older releases (down to 2008.2) might work but are not supported. Perl Compatibility The 2012.2 release of P4Perl is supported building from source with Perl 5.12, 5.14, and 5.16 The P4Perl 32-bit Windows installer requires Perl 5.14 32-bit. The P4Perl 64-bit Windows installer requires Perl 5.14 64-bit. OpenSSL Compatibility To build P4Perl with encrypted communication support, you must use the version of OpenSSL that Perforce C/C++ API has been built against. Running P4Perl linked to an older library will fail with the error: "SSL library must be at least version 1.0.1." The 2012.2 release of P4Perl is supported with OpenSSL 1.0.1. For detailed compatibility, please check the following table: Perforce C/C++ API Version | OpenSSL Release ============================================ 2012.1 | 1.0.0 2012.2 | 1.0.1 Platform Compatibility While P4Perl is generally portable, this release is certified only on the following platforms: Linux 2.6 Intel (x86, x86_64) Solaris 10 Intel (x86) Windows XP SP2+, 2003, Vista, 7, 2008 Intel (x86, x86_64) FreeBSD 6.0, 7.0 Intel (x86, x86_64) Mac OS X 10.6, 10.7, 10.8 (x86_64) Note: As of 2012.1, a universal build of the Perforce C/C++ API is no longer available for Darwin or Mac OS X. P4Perl is now a 64-bit only library on Darwin. This has been tested with a universal build of Perl and is known to work. 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. The Windows installer was built with ActivePerl 5.14 and Visual Studio 2008. Compatibility with Previous Releases P4Perl 2012.2 is backwards-compatible with all previous releases from Perforce Software. Known Limitations The Perforce client-server protocol is not designed to support multiple concurrent queries over the same connection. For this reason, multi-threaded applications using the C++ API or the script APIs (P4Perl, P4Ruby, etc.) should ensure that a separate connection is used for each thread or that only one thread may use a shared connection at a time. 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 ClearHandler() Clears the active results handler GetHandler() Returns the results handler object SetHandler() Sets the results handler object 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 -------------------------------------------------------------------------- New functionality in 2012.2 #507841 (Bug #56481) * Added RunTickets() method to list local tickets. Note that $p4->Run("tickets") still gives the old error message "Must upgrade to 2004.2 p4 to access tickets." #509303 (Bug #56513) * ** *** Support for the new progress indicator API. P4Perl supplies a new progress attribute, which can take an instance of P4::Progress class or subclass. Progress information is currently only supported for submits and 'sync -q'. Details can be found in the documentation. (perldoc P4::Progress) #499606 (Bug #56518) * New convenience method P4::IterateSpec that allows easy iteration through some or all spec objects such as clients or changes. The P4Perl implementation provides two methods next() and hasNext(). Details can be found in the documentation. (perldoc P4::IterateSpec) Bugs fixed in 2012.2 #513154 (Bug #59168) * Added abstract class P4::OutputHandler and renamed the methods introduced in 2011.1 to match case consistence used P4Perl. Change also includes the addition of perldoc for P4::OutputHandler. (perldoc P4::OutputHandler) Deprecated Method New Method ---------------------- ---------------------- outputMessage() OutputMessage() outputText() OutputText() outputInfo() OutputInfo() outputBinary() OutputBinary() outputStat() OutputStat() #509755 (Bug #58125) * Correction to perldoc for P4::Message and P4 to identify a return type of string when calling $p4->Errors or $p4->Warnings and a return type of P4::Message object for $p4->Messages. #504636 (Bug #57507) ** API change to allow P4Perl on Windows to call '$p4->GetEnv()' after setting 'use P4;' to fetch environment variables. #501503 (Bug #58484) * Added missing 'StreamAtChange' field to cached specs. #498724 (Bug #58284) * Specs returning results with arrays of hashed elements are now null padded. Enabling the alignment of values when indexed into the hash. -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2012.1 #400839 (Bug #51850) * ** *** Enable "action resolve" to support resolves of branches, deletes and file types. The existing P4::Resolver class has been extended with a new method ActionResolve() that will be invoked if an "action resolve" is required. Details can be found in the documentation. #414329 (Bug #51634) * ** *** P4Perl supports SSL connections if compiled with SSL support. Instructions on how to compile with SSL support can be found at the top of this document under "Building P4Python from Source" and in the documentation. P4.identify() will then report the version of the OpenSSL library used. Library used for building the Perforce C++ API (not the version P4Python is linked against). Bugs fixed in 2012.1 #446673 (Bug #54196, #55063) * Fixed action-resolve test hardness after server change of the default integration algorithm #421813 (Bug #51749) * Fixed unreferenced scalar reported when attempting to free P4Results array. #424055 (Bug #51637) * Minor fix to version string when building distribution. Separated Makefile version parsing into a new class Build::Version #421820 (Bug #51752) * When using a UTF16 or UTF32 charset P4Perl would attempt to format the command output messages in the same format. Fixed to format client messages in UTF8. #420702 (Bug #51758) * Perl would crash with a segmentation fault if a custom Resolver object was used to resolve binary files. Fixed. -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2011.1 #338403 (Bug #47451) * Added a SetEnv() method to set P4 environment variables in the host's registry (available on Windows and OS X). #328168 (Bug #45860) * ** Enabled streams output as the default where the API level is greater than 69. #319432 (Bug #42249) * Added new callback handler for processing results. P4::Spec results can now be processed individually using a set of method callbacks from a user defined object. The user defined object is set with the new method call SetHandler() and must implement the following methods: outputMessage() outputText() outputInfo() outputBinary() outputStat() Bugs fixed in 2011.1 #406719 (Bug #43424) * Running 'print' on a file that started with '---' won't output its content as it is interpreted as track output even if track output is not enabled. This is now fixed. There is still an oddity when p4.track = 1 and a user runs p4.run_print() on a file that only has lines starting with '--- '. In that case, the output of the print is lost. Disable tracking by setting p4.track = 0 (the default) will solve this problem. #385159 (Bug #49324) ** On Windows Vista, Windows 7, or Windows 2008, a client running as Administrator would fail to properly process file names in non-ASCII character sets (such as Shift-JIS). #328944 (Bug #41272) *** Find ExtraTag fields such as 'firmerThanParent' and includes them in the returned hash. Including additional tests in 16-streams. #328563 (Bug #42097) * Change order of P4API version string, now formatted as below: (2011.1/308885 API) #328186 (Bug #42097) * Updated the reported version strings for P4Perl and P4API. #319431 (Bug #43791) ** Bug fix for regression test 11-login.t -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2010.2 #261035 * Added new track option. For more details about server performance tracking see: http://kb.perforce.com/article/883 #244195 * New P4::Messages() method returns an array of P4::Message() objects, one for each message (info, warning or error) sent by the server. The methods of this class allow script writers to test the severity of the error and the generic reason for the error as well as accessing the error message itself. Bugs fixed in 2010.2 #291396 (Bug #43424) * Running 'print' on a file that started with '---' won't output its content as it is interpreted as track output even if track output is not enabled. This is now fixed. There is still an oddity when p4.track = 1 and a user runs p4.run_print() on a file that only has lines starting with '--- '. In that case, the output of the print is lost. Disable tracking by setting p4.track = 0 (the default) will solve this problem. -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2010.1 #23152 * Added new ServerUnicode() method that allows script writers to test whether or not a Perforce Server is in internationalized (unicode) mode. #231550 * It's no longer necessary to execute a command against the server before calling ServerLevel(), or ServerCaseSensitive(). If no command has been run, then P4Perl will automatically run a 'p4 info' in order to gather the required information. #230105 * Three new class constants have been added to the P4 class: $P4::VERSION = The P4Perl version string $P4::PATCHLEVEL = The P4Perl patch level $P4::OS = The OS name as P4Perl sees it Bugs fixed in 2010.1 (none) -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2009.2 #215001 (Bug #35415) A new method, P4::ServerCaseSensitive(), enables scripts to detect whether a server is case-sensitive. Detection can only be done after a command has been executed on the connection. #214996 (Bug #32915) P4::SetPort() no longer permits the user to change the port after the client has connected. Bugs fixed since first release (228098) #243114 (Bug 38769#) * P4Perl no longer crashes when attempting to parse the jobspec. Bugs fixed in 2009.2 #215000 (Bug #35411) * P4Perl now correctly tracks disconnects from the server. #222728 (Bug #36569) * The Map class removed '-' and '+' from the path if the form Map::Insert(lhs, rhs) was used, even if these characters did not appear at the beginning of the path. Now dashes and pluses are preserved within the path. -------------------------------------------------------------------------- -------------------------------------------------------------------------- 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.