<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <TITLE>Tony Smith's P4Ruby - Perforce Public Depot</TITLE> <META content="text/html; charset=iso8859-1" http-equiv=Content-Type> <LINK REL="stylesheet" TYPE="text/css" HREF="../../../shared/rubystyle.css"> </HEAD> <BODY> <table width="100%" border=0> <tr> <td> <img src="../../../images/ruby2.jpg"> </td> <td> <H2>P4Ruby: Ruby interface to the Perforce API</H2> </td> </tr> </table> <h3>Introduction</h3> <p> 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: <ul> <li>Get Perforce data and forms in hashes and arrays <li>Edit Perforce forms by modifying hashes <li>Exception based error handling <li>Ignore warnings (like "File(s) up-to-date." on a sync) <li>Run as many commands on a connection as you want to </ul> <p> Writing Ruby code is a joy for all programmers, and P4Ruby makes that experience available to Perforce users. Enjoy it! <h3>Licence</h3> <p>This extension is distributed under the terms of <a href="main/LICENSE">this</a> license, which is a BSD-like license. You use it at your own risk. <h3>Getting Started</h3> <h4>1. Get Ruby</h4> Linux users can probably skip this step as most Linux distributions these days come with Ruby installed (or on the CD's) <p> FreeBSD users can just use pkg_add to install ruby as there's a FreeBSD port for it. <p> Windows users can download a Windows installer for Ruby from <a href=http://rubyinstaller.sourceforge.net/>http://rubyinstaller.sourceforge.net/</a> 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. <p> Otherwise you can download the source for Ruby from <a href="http://www.ruby-lang.org">http://www.ruby-lang.org</a> which is the main Ruby home page. <h4>2. Get P4Ruby</h4> 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: <p> <table border="1"> <tr> <th>Release Type</th> <th>Source Code</th> <th>Installer (Ruby 1.6.x)</th> <th>Installer (Ruby 1.8.x)</th> </tr> <tr> <td>Stable</td> <td> <a href="release/P4Ruby-1.3578.tar.gz">P4Ruby-1.3578.tar.gz</a> (latest) <br> <a href="release/P4Ruby-1.1750.tar.gz">P4Ruby-1.1750.tar.gz</a> (first stable release) </td> <td> <a href="release/p4ruby-1.3578-1.6.8-setup.exe">p4ruby-1.3578-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.3578-1.8.0-setup.exe">p4ruby-1.3578-1.8.0-setup.exe</a> </td> </tr> <tr> <td>Current</td> <td> <a href="current/P4Ruby.tar.gz">P4Ruby.tar.gz</a> </td> <td> <a href="current/p4ruby-main-1.6.8-setup.exe">p4ruby-main-1.6.8-setup.exe</a> </td> <td> <a href="current/p4ruby-main-1.8.0-setup.exe">p4ruby-main-1.8.0-setup.exe</a> </td> </tr> </table> <p> Read the <a href="main/Changes">Change history</a> <p> If you used the Windows installer then the following steps are not necessary for you, you're all set. <h4>3. Get the Perforce API</h4> This step is only required if you're building P4Ruby from source. <p> See the <a href="#porting">Porting Matrices</a> below to help you find the right Perforce API build for your platform. <p> If your platform is not there, go to the <a href="http://www.perforce.com/downloads/perforce/">Perforce download</a> site and grab the p4api.tar file for your platform. Try to get the latest available release, but certainly no older than 2001.1. <p> Extract the files in the p4api.tar tarfile (WinZip can handle it for Windows users) into a new empty directory and remember its location. <h4>4. Build and install P4Ruby</h4> <p> Follow the build instructions in P4Ruby's README file. <h3>Documentation</h3> 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 <a href="http://www.rubycentral.com/book/index.html">here</a> but I'd thoroughly recommend buying a paper copy too. <p> P4Ruby's documentation is <a href="main/doc/index.html">here</a> <h3>P4Ruby Script Library</h3> I've started collecting a <a href="../../P4Rubylib/index.html">library</a> of triggers and scripts based on P4Ruby. If you've a script you'd like to see included, please <a href="mailto:tony@smee.org">contact me</a> and let me know. <h3>Support</h3> P4Ruby is <b>not</b> supported by Perforce Software. It's supported by me personally so please send cries for help/comments/suggestions/ports/patches etc to <a href="mailto:tony@smee.org">tony@smee.org</a>. I'll deal with them as quickly as possible. <a name="porting"> <h3>Porting Matrices</h3> 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. <p> 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. <p> <b>If you get "unresolved symbol" errors when building or running P4Ruby, you probably used the wrong compiler or the wrong Perforce API build.</b> <h4>Linux Builds</h4> <table border="1" cellpadding="5"> <tr> <th>Kernel version</th> <th>glibc version</th> <th>gcc version</th> <th>Perforce API Download</th> </tr> <tr> <td>2.2.x</td> <td>2.x</td> <td>2.9x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r02.2/bin.linux22x86/p4api.tar">2002.2/LINUX22x86</a> </td> </tr> <tr> <td>2.4.x</td> <td>2.x</td> <td>2.9x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.linux24x86/p4api.tar">2003.2/LINUX24x86</a> </td> </tr> <tr> <td>2.4.x</td> <td>2.x</td> <td>3.x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.linux80x86/p4api.tar">2003.2/LINUX80x86</a> </td> </tr> <tr> <tr> <td>2.6.x</td> <td>2.x</td> <td>3.x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.linux80x86/p4api.tar">2003.2/LINUX80x86</a> </td> </tr> <tr> </table> <h4><font color="#cc3333">FreeBSD Builds</font></h4> <table border="1" cellpadding="5"> <tr> <th>FreeBSD version</th> <th>gcc version</th> <th>Perforce API Download</th> </tr> <tr> <td>4.x</td> <td>2.9x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.freebsd4/p4api.tar">2003.2/FREEBSD4</a> </td> </tr> <tr> <td>5.x</td> <td>2.9x</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.freebsd4/p4api.tar">2003.2/FREEBSD4</a> </td> </tr> </table> <h4><font color="#cc3333">Windows Builds</font></h4> <table border="1" cellpadding="5"> <tr> <th>Windows version</th> <th>Perforce API Download</th> </tr> <tr> <td>Windows NT/2000/XP/2003</td> <td> <a href="http://www.perforce.com/downloads/perforce/r03.2/bin.ntx86/p4api.tar">2003.2/NTx86</a> </td> </tr> </table> <h3>Sample code</h3> 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. <PRE> 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 </PRE> <h3>Credits</h3> Thanks to <a href="mailto:robert@vaccaperna.co.uk">Robert Cowham </a> for getting me started with a Windows installer. <p> Thanks to Dave Thomas and Andy Hunt at <a href="http://www.pragmaticprogrammer.com">The Pragmatic Programmers</a> for their superb book and kindly giving me permission to use the funky Ruby image at the top of this page. <p> And of course, thanks to Matz for Ruby. </BODY></HTML>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#26 | 6259 | Tony Smith | Update P4Perl/P4Ruby html pages with deprecation notice. | ||
#25 | 6005 | Tony Smith | Release P4Ruby 1.5953 as latest stable release | ||
#24 | 5996 | Tony Smith | Fix broken link | ||
#23 | 5822 | Tony Smith | Fix broken links due to transposed digits in version number. | ||
#22 | 5771 | Tony Smith |
Release P4Ruby 1.5768 as latest stable release. There are some larger changes in the pipe, so I'm releasing the existing code before they come through. |
||
#21 | 5106 | Tony Smith |
P4Ruby installers for version 1.5105. Note that the Ruby 1.8 installer is now built with Ruby 1.8.2. |
||
#20 | 4847 | Tony Smith |
Update stable release of P4Ruby to 1.4841 as it fixes an annoying bug in the previous stable release. |
||
#19 | 4829 | Tony Smith | Release build 1.4809 of P4Ruby as the latest stable release. | ||
#18 | 4660 | Tony Smith | Some doc tidying. | ||
#17 | 4590 | Tony Smith | Update link to Ruby installer | ||
#16 | 4260 | Tony Smith |
Call P4Ruby 1.4251 the latest stable release and update web page accordingly. |
||
#15 | 4254 | Tony Smith | Convert P4Ruby pages to CSS style sheet instead of horrid tags. | ||
#14 | 4250 | Tony Smith | Simplify porting matrices and add a link to the P4Ruby library. | ||
#13 | 3655 | Tony Smith |
Change the location of the images in the P4Ruby index page and update the porting matrix. |
||
#12 | 3581 | Tony Smith |
Release 1.3578 source code and installers and update web page accordingly |
||
#11 | 2598 | Tony Smith | Update porting matrices for P4Perl and P4Ruby | ||
#10 | 2580 | Tony Smith |
Update build matrices for P4Perl and P4Ruby as both compile and work happily with the 2002.2 API. |
||
#9 | 2435 | Tony Smith | HTML tidying and some corrections from Robert C. | ||
#8 | 2428 | Tony Smith |
Just a few more minor tweaks. Add some credits and slightly expand the example code. |
||
#7 | 2427 | Tony Smith | A couple of minor tweaks | ||
#6 | 2426 | Tony Smith | Doc beautifying for P4Ruby. | ||
#5 | 1917 | Tony Smith | Clean up previous change. | ||
#4 | 1916 | Tony Smith | Update P4Ruby pages to show 1.1750 stable build | ||
#3 | 1413 | Tony Smith | Correct name of tarball archive. | ||
#2 | 1324 | Tony Smith |
P4/Ruby documentation update. Changed doc layout and added in docs for newly added methods and classes. |
||
#1 | 1164 | Tony Smith |
Reworked exception handling (hopefully for the last time) in P4/Ruby. Now exceptions are raised on completion of Perforce commands if any errors or warnings were received as part of executing the command. This change also adds documentation, and indexes the Ruby interface off my main page. Bad form to combine so many changes in one changelist, but it's getting late and I want to get them submitted! |