Release Notes for P4Ruby, the Ruby interface to the Perforce SCM System GA Release 2007.3 April 8, 2008 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 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 P4Ruby, run the following command: ruby -rP4 -e "puts P4.identify" Building P4Ruby 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: ruby p4conf.rb --apidir make (on Unix) nmake (on Windows) ruby test.rb NOTE: The test harness requires that 'p4d' be installed and in the PATH 4. To install P4Ruby, 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 P4Ruby with any release of the Perforce server later than 2001.1 2. API Compatibility The 2007.3 release of P4Ruby supports the 2007.3 Perforce API. Older releases (down to 2006.2) may also work, but they are not supported. 3. Ruby compatibility The 2007.3 release of P4Ruby is compatible with Ruby 1.8 4. Platform compatibility While P4Ruby is generally portable, this release is certified only on the following platforms: Linux Solaris Windows FreeBSD 5. 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, 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 .NET 2003 must be used to compile P4Ruby. Note that this may require a change to one of Ruby's header files: 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. Most Windows users will want to use the Windows Installer available from the Perforce website. 6. Compatibility with Previous Releases There are no previous releases of P4Ruby from Perforce Software Inc. 7. Compatibility with P4Ruby from the Public Depot Perforce P4Ruby is significantly different from the P4Ruby in the Perforce Public Depot. It contains several improvments as well as interface changes intended to make P4Ruby consistent with the other scripting interfaces, and with Ruby in general. Users migrating from Public Depot Ruby 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: 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 will be using 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: see also the renamed methods below, as some of these method names have been re-used as attribute readers (instead of writers). 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 given names that ended in a question mark ('?'), but the convention in Ruby is that only methods that return booleans should have names with this ending. 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: 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 may be turned on and off at will by using: p4.tagged = false # Disabled p4.tagged = true # Enabled Since 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 -------------------------------------------------------------------------------- Bugs Fixed since first release (2007.3/147242) #151167 * The Makefile generated on some Linux platforms (notably Ubuntu 7.10) was not correct, and attempted to link P4Ruby using 'cc' instead of 'c++'. This caused an 'undefined symbol' error (typically '_ZTVN10__cxxabiv120__si_class_type_infoE') , when attempting to use P4Ruby. This problem has been corrected (Bug#job028774) #150577 * 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#run_filelog. This occurred because a digest and filesize were allocated to the deleted revision. This problem has been corrected. (Bug #28704) #150576 * P4::Revision#filesize() was broken, and always returned nil. This problem has been corrected. (Bug #28773)