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 basically the BSD 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 the Perforce API

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.

3. 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:

Stable release P4Ruby-1.1750.tar.gz (first stable release)  
Current release P4Ruby.tar.gz
installer for Windows 		View the latest changes

Once you've done that, unpack the tarball and see the README file for build instructions.

Documentation

Read the fine manual here

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 Matrix

P4Ruby has been ported to at least the following platforms. There may be others out there as it's pretty portable. If you do port it to another platform and you have to make changes to get it to build, please let me know.

Platform Perforce API Build Ruby Versions Notes
Linux (glibc 2.2, gcc 2.96 and 2.95.3) 2001.1 Linux 2.2 Ruby 1.6.4  
Linux (glibc 2.2, gcc 2.96 and 2.95.3) 2002.1 Linux 2.4 Ruby 1.6.6  
Linux (glibc 2.2, gcc 2.95.3) 2002.1 Linux 2.4 Ruby 1.6.7  
FreeBSD 4 (gcc 2.95.3) 2002.1 FreeBSD 4 Ruby 1.6.6  
Windows 2000 2001.1 NTx86 Ruby 1.6.5
Windows 2000 2002.1 NTx86 Ruby 1.6.7

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 )

  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