Release Notes for P4Ruby, Perforce's derived API for Ruby Version 2009.2 Introduction This document lists all user-visible changes to P4Ruby from release 2007.3, the first supported P4Ruby 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 P4Ruby, issue the following command: ruby -rP4 -e "puts P4.identify" -------------------------------------------------------------------------- Building P4Ruby from Source 1. Download the appropriate Perforce C++ API build from the Perforce FTP site at "ftp.perforce.com/perforce". OS X users must get the universal binary version of the API in the "bin.darwin*u" directory. Windows users must get "p4api_vs2008_static.zip" in the "bin.ntx86" directory. Then, unzip the archive into an empty directory. 2. Extract the P4Ruby API archive into a new, empty directory. 3. Issue the following commands: ruby p4conf.rb --apidir UNIX: make Windows: nmake For a clean install, remove the directory created in step 2, then re-extract the archive. To verify that the build succeeded, run the test script: ruby test.rb The Perforce server executable p4d must be installed and in the PATH. 4. To install P4Ruby, issue the following command. On UNIX systems, this step must be run as root: make install -------------------------------------------------------------------------- Compatibility Statements Server Compatibility You can use any release of P4Ruby with any release of the Perforce server later than 2001.1 API Compatibility The 2009.2 release of P4Ruby supports the 2009.2 Perforce API. Older releases (down to 2008.2) might work but are not supported. Ruby compatibility The 2009.2 release of P4Ruby is compatible with Ruby 1.8 The P4Ruby Windows installer was built with Visual Studio 2008 and Ruby 1.8. Platform compatibility While P4Ruby is generally portable, this release is certified only on the following platforms: Linux 2.6 x86 Solaris 10 x86 NT x86 FreeBSD 6 x86 Mac OSX 10.5 x86 Compiler Compatibility To build P4Ruby from source, you must use a version of Ruby 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 causes linker errors due to differences in name handling between compilers. Although Ruby 1.8 was not compiled on Windows platforms with Visual Studio 2008, P4Ruby can be compiled with Visual Studio 2008. If the build fails with the following error: c:\ruby\lib\ruby\1.8\i386-mswin32\config.h(2) : fatal error C1189: #error : MSC version unmatch edit the config.h file to remove the MSC version check and recompile. Windows users can use the Windows installer available from the Perforce web site. Compatibility with Previous Releases Unless otherwise stated below, the 2009.2 release of P4Ruby is compatible with previous releases from Perforce Software. Compatibility with P4Ruby from the Public Depot Perforce P4Ruby is significantly different from the P4Ruby in the Perforce Public Depot. It contains several improvements and interface changes intended to make P4Ruby consistent with the other scripting interfaces, and with Ruby in general. If you are migrating from Public Depot P4Ruby, 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: output The output is returned by the run* methods parse_forms Form parsing is now always on tagged See tagged? and tagged= below. Public Depot P4Ruby also contained compatibility interfaces for the following methods, all of which have been removed. In these cases, the method on the right-hand side has also been in Public Depot P4Ruby for some time, and most scripts use that form already. Public Depot Method Perforce P4Ruby Method ------------------- ---------------------- cwd cwd= client client= host host= port port= user user= debug debug= exception_level exception_level= NOTE: Some of these method names have been re-used as attribute readers (instead of writers). See the following list of new methods. New Methods ----------- The following methods are new to Perforce P4Ruby: api_level Returns the API compatibility level connected? Returns true if the client is connected maxresults Returns the current maxresults limit maxscanrows Returns the current maxscanrows limit maxlocktime Returns the current maxlocktime limit maxlocktime= Sets the current maxlocktime limit p4config_file Returns the path of the P4CONFIG file prog Returns the name of the program (if set) server_level Returns the (numeric) level of the server tagged? Returns true if tagged mode is enabled tagged= Enable or disable tagged mode ticket_file Returns the path to the current ticket file ticket_file= Sets the path to the current ticket file version Returns the version of the script version= Sets the version of the script Renamed Methods --------------- In Public Depot P4Ruby, many methods were assigned names that end in a question mark (?), but the convention in Ruby is that only methods that return booleans have names ending with a question mark. Perforce P4Ruby follows this convention, so the following methods in Public Depot P4Ruby have been renamed according to the table below: Public Depot Method Perforce P4Ruby Method ------------------- ---------------------- charset? charset client? client cwd? cwd exception_level? exception_level host? host password? password port? port user? user In addition, the following methods have been renamed for clarity and consistency across the Perforce scripting interfaces: Old name New name -------- -------- api= api_level= submit_spec run_submit Tagged Mode and Form Parsing ---------------------------- In Public Depot P4Ruby, tagged output and form parsing mode were off by default, but most scripts turned them on immediately. In Perforce P4Ruby, both form parsing and tagged output are on by default. Form parsing cannot be explicitly disabled, but tagged output can be turned on and off by setting p4.tagged as follows: p4.tagged = false # Disabled p4.tagged = true # Enabled Because form parsing does not work when tagged output is disabled, this method can be used to disable form parsing if necessary. -------------------------------------------------------------------------- Key to symbols used in change notes below. * -- requires new P4Ruby ** -- requires P4Ruby built with new P4API *** -- requires new p4d server program -------------------------------------------------------------------------- New functionality in 2009.2 #214454 (Bug #32916) * P4#port= now raises a P4Exception if called after P4#connect(). #214449 (Bug #35416) * Added a P4#server_case_sensitive? method that enables scripts to detect whether the server is case-sensitive. Cannot be called until a command has been issued to the server. Bugs fixed in 2009.2 #214445,214999 (Bug #35410) * P4Ruby now correctly tracks disconnects from the server. #222727 (Bug #36568) * 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 #191900 (Bug #26729) * A new method: P4#tagged( aBool ) { block } has been added to the P4 class. This method temporarily toggles the use of tagged output for the duration of the block and resets it when the block terminates. Bugs fixed in 2009.1 #191889 (Bug #29911) * Calling P4#run_resolve() or P4#run( 'resolve' ) without a block or a previous call to P4#input no longer causes an infinite loop. #191623,191627 (Bug #32918) * P4Ruby now correctly parses jobs when the jobspec contains field names ending in numbers. -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2008.2 #162422 (Bug #30364) * #166158 * A new class, P4::Map, enables users to create and use Perforce mappings without requiring a connection to a server. Methods in the P4::Map class are: P4::Map.new Constructor P4::Map.join Join two maps to create a third P4::Map#clear Empty a map P4::Map#count Return the number of entries P4::Map#empty? Tests whether a map object is empty P4::Map#insert Inserts an entry into the map P4::Map#translate Translate a string through a map P4::Map#includes? Tests whether a path is mapped P4::Map#reverse Swap left and right sides of the mapping P4::Map#lhs Returns the left side as an array P4::Map#rhs Returns the right side as an array P4::Map#to_a Returns the map as an array Bugs fixed in 2008.2 #169159 (Bug #29935, Bug #31096) * #165338 * P4Ruby now correctly loads the value of P4CHARSET from the environment. -------------------------------------------------------------------------- -------------------------------------------------------------------------- New functionality in 2008.1 #152356 (Bug #29022) * A new method 'P4#env( 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#cwd= now loads any P4CONFIG file settings that are appropriate to the new working directory. #153005 (Bug #29308) * P4Ruby now supports Mac OS X 10.5. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Bugs fixed in 2007.3 #151167 (Bug #28774) * The Makefile generated on some Linux platforms (notably Ubuntu 7.10) was not correct, and attempted to link P4Ruby using 'cc' instead of 'c++', causing an 'undefined symbol' error (typically '_ZTVN10__cxxabiv120__si_class_type_infoE') , when attempting to use P4Ruby. This problem has been corrected. #150577 (Bug #28704) * The presence of deleted revisions in a file's history might lead to incorrect fileSize and digest attributes for other revisions in the output of P4#run_filelog. This problem has been corrected. #150576 (Bug #28773) * P4::Revision#filesize() always returned nil. This problem has been corrected.