P4Ruby: Ruby interface to the Perforce API

Introduction

So, what's it all about? Well in a nutshell P4Ruby allows you to write beautiful Ruby code that interacts with a Perforce server. The main features are:

Writing Ruby code is a joy for all programmers, and P4Ruby makes that experience available to Perforce users. Enjoy it!

Licence

This extension is distributed under the terms of this license, which is a BSD-like license. You use it at your own risk.

Getting Started

1. Get Ruby

Linux users can probably skip this step as most Linux distributions these days come with Ruby installed (or on the CD's)

FreeBSD users can just use pkg_add to install ruby as there's a FreeBSD port for it.

Windows users can download a Windows installer for Ruby from http://rubyinstaller.sourceforge.net/ They can also grab a P4Ruby installer from the links below - useful if you don't have Visual Studio installed. If you do this, then obviously you don't need to do any of the other build steps.

Otherwise you can download the source for Ruby from http://www.ruby-lang.org which is the main Ruby home page.

2. Get P4Ruby

Pick the build of P4Ruby you want to run. I do maintain a "stable" release and a current release, but it's pretty darn stable these days so I tend to recommend the current release mostly. If you absolutely don't want the latest and greatest, then use the stable release. Otherwise current's what you want. Here are the downloads:

Release Type Source Code Installer (Ruby 1.6.x) Installer (Ruby 1.8.x)
Stable P4Ruby-1.3578.tar.gz (latest)
P4Ruby-1.1750.tar.gz (first stable release) 		p4ruby-1.3578-1.6.8-setup.exe p4ruby-1.3578-1.8.0-setup.exe
Current P4Ruby.tar.gz p4ruby-main-1.6.8-setup.exe p4ruby-main-1.8.0-setup.exe

Read the Change history

If you used the Windows installer then the following steps are not necessary for you, you're all set.

3. Get the Perforce API

This step is only required if you're building P4Ruby from source.

See the Porting Matrices below to help you find the right Perforce API build for your platform.

If your platform is not there, go to the Perforce download site and grab the p4api.tar file for your platform. Try to get the latest available release, but certainly no older than 2001.1.

Extract the files in the p4api.tar tarfile (WinZip can handle it for Windows users) into a new empty directory and remember its location.

4. Build and install P4Ruby

Follow the build instructions in P4Ruby's README file.

Documentation

If you're new to Ruby, then I can't recommend highly enough "Programming Ruby" by Dave Thomas and Andy Hunt. The online copy of the book is available here but I'd thoroughly recommend buying a paper copy too.

P4Ruby's documentation is here

P4Ruby Script Library

I've started collecting a library of triggers and scripts based on P4Ruby. If you've a script you'd like to see included, please contact me and let me know.

Support

P4Ruby is not supported by Perforce Software. It's supported by me personally so please send cries for help/comments/suggestions/ports/patches etc to tony@smee.org. I'll deal with them as quickly as possible.

Porting Matrices

P4Ruby is as portable as Ruby and Perforce so porting it is relatively easy. Most of the porting problems revolve around people not knowing which build of the Perforce API to use. The key is to match up the compiler used to build Ruby with the compiler used to build Perforce and use that compiler to build P4Ruby. Simple. So below you'll find some matrices to (a) illustrate the point and (b) link to the API builds required to build the current P4Ruby with the current versions of Ruby and Perforce.

Note that P4Ruby is compatible with older versions of Ruby and the Perforce API, so on older platforms you should still be able to get a working build.

If you get "unresolved symbol" errors when building or running P4Ruby, you probably used the wrong compiler or the wrong Perforce API build.

Linux Builds

Kernel version glibc version gcc version Perforce API Download
2.2.x 2.x 2.9x 2002.2/LINUX22x86
2.4.x 2.x 2.9x 2003.2/LINUX24x86
2.4.x 2.x 3.x 2003.2/LINUX80x86
2.6.x 2.x 3.x 2003.2/LINUX80x86

FreeBSD Builds

FreeBSD version gcc version Perforce API Download
4.x 2.9x 2003.2/FREEBSD4
5.x 2.9x 2003.2/FREEBSD4

Windows Builds

Windows version Perforce API Download
Windows NT/2000/XP/2003 2003.2/NTx86

Sample code

Just a small example to whet your appetite. This small sample shows how to create a new client workspace based on an existing template. You can of course construct the view manually but most people who are scripting client creation will use a template so that seemed like a good example. 
  require "P4"

  template 	= "my-client-template"
  client_root	= "c:\\p4-work"

  p4 = P4.new
  p4.parse_forms
  p4.connect

  begin
    # Run a "p4 client -t template -o" and convert it into a Ruby hash
    spec = p4.fetch_client( "-t", template )

    # Now edit the fields in the form
    spec[ "Root" ] 	= client_root
    spec[ "Options" ]	= spec[ "Options" ].sub( "normdir", "rmdir" )

    # Now save the udpated spec
    p4.save_client( spec )

    # And sync it.
    p4.run_sync

  rescue P4Exception
    # If any errors occur, we'll jump in here. Just log them
    # and raise the exception up to the higher level

    p4.errors.each { |e| $stderr.puts( e ) }
    raise
  end

Credits

Thanks to Robert Cowham for getting me started with a Windows installer.

Thanks to Dave Thomas and Andy Hunt at The Pragmatic Programmers for their superb book and kindly giving me permission to use the funky Ruby image at the top of this page.

And of course, thanks to Matz for Ruby.