<!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>Contents</h3> <ol> <li><a href="#intro">Introduction</a></li> <li><a href="#license">License</a></li> <li><a href="#support">Support</a></li> <li><a href="#doc">Documentation</a></li> <li><a href="#build">Building P4Ruby</a></li> <li><a href="#downloads">Downloads</a></li> <li><a href="#sample">Sample Code</a></li> <li><a href="#lib">P4Ruby Script Library</a></li> <li><a href="#porting">Porting</a></li> <li><a href="#credits">Credits</a></li> </ol> <a name="intro"></a> <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! <a name="license"></a> <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. <a name="support"></a> <h3>Support</h3> P4Ruby is <b>not</b> supported by Perforce Software. It's supported by me personally. Please subscribe to the <a href="http://maillist.perforce.com/mailman/listinfo/p4ruby">p4ruby mailing list</a> and send all P4Ruby related questions, comments, patches etc. to the list. If you really can't use the list, you can contact me directly at: <a href="mailto:tony@smee.org">tony@smee.org</a>. If possible, please use the list. <a name="doc"></a> <h3>Documentation</h3> <ul> <li><a href="main/doc/index.html">P4Ruby Programmers Guide</a></li> <li><a href="http://www.rubycentral.com/pickaxe/">Programming Ruby</a> (online edition for Ruby 1.6)</li> </ul> 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 using the link above, but I'd thoroughly recommend buying a paper copy too. They've recently announced a 2nd edition of the book too, updated for Ruby 1.8 <a name="build"></a> <h3>Building P4Ruby</h3> <h4>1. Download and install 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.rubyforge.org/wiki/wiki.pl">http://rubyinstaller.rubyforge.org/wiki/wiki.pl</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. Download P4Ruby</h4> Choose the build of P4Ruby you want to run. I do maintain a "stable" release and a current release, but it's all pretty 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. Pick the appropriate file from the <a href="#downloads">downloads</a> section. <p> <b> If you chose to use the Windows installer then the process ends here. You're ready to start using P4Ruby. </b> What follows is only applicable to those building P4Ruby from source. <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</a> section below to help you find the right Perforce API build for your platform. <p> Then 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. <a name="downloads"></a> <h3>Downloads</h3> <h4>Current Builds</h4> <table border="1"> <tr> <th>Release Type</th> <th>Source Code</th> <th>API Version</th> <th>Installer (Ruby 1.6.x)</th> <th>Installer (Ruby 1.8.x)</th> </tr> <tr> <td>Current</td> <td> <a href="current/P4Ruby.tar.gz">P4Ruby.tar.gz</a> </td> <td>Latest</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.2-setup.exe">p4ruby-main-1.8.2-setup.exe</a> </td> </tr> <tr> <td>Latest Stable</td> <td> <a href="release/P4Ruby-1.5953.tar.gz">P4Ruby-1.5953.tar.gz</a> </td> <td><b>2007.2</b></td> <td> <a href="release/p4ruby-1.5953-1.6.8-setup.exe">p4ruby-1.5953-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.5953-1.8.2-setup.exe">p4ruby-1.5953-1.8.2-setup.exe</a> </td> </tr> </table> <h4>Older Stable Builds</h4> <table border="1"> <tr> <th>Source Code</th> <th>Installer (Ruby 1.6.x)</th> <th>Installer (Ruby 1.8.x)</th> </tr> <tr> <td> <a href="release/P4Ruby-1.5768.tar.gz">P4Ruby-1.5768.tar.gz</a> </td> <td> <a href="release/p4ruby-1.5768-1.6.8-setup.exe">p4ruby-1.5768-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.5768-1.8.2-setup.exe">p4ruby-1.5768-1.8.2-setup.exe</a> </td> </tr> <tr> <td> <a href="release/P4Ruby-1.4841.tar.gz">P4Ruby-1.4841.tar.gz</a> </td> <td> <a href="release/p4ruby-1.4841-1.6.8-setup.exe">p4ruby-1.4841-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.4841-1.8.0-setup.exe">p4ruby-1.4841-1.8.0-setup.exe</a> </td> </tr> <tr> <td> <a href="release/P4Ruby-1.4809.tar.gz">P4Ruby-1.4809.tar.gz</a> </td> <td> <a href="release/p4ruby-1.4809-1.6.8-setup.exe">p4ruby-1.4809-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.4809-1.8.0-setup.exe">p4ruby-1.4809-1.8.0-setup.exe</a> </td> </tr> <tr> <td> <a href="release/P4Ruby-1.4251.tar.gz">P4Ruby-1.4251.tar.gz</a> </td> <td> <a href="release/p4ruby-1.4251-1.6.8-setup.exe">p4ruby-1.4251-1.6.8-setup.exe</a> </td> <td> <a href="release/p4ruby-1.4251-1.8.0-setup.exe">p4ruby-1.4251-1.8.0-setup.exe</a> </td> </tr> <tr> <td> <a href="release/P4Ruby-1.3578.tar.gz">P4Ruby-1.3578.tar.gz</a> </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> <td> <a href="release/P4Ruby-1.1750.tar.gz">P4Ruby-1.1750.tar.gz</a> (first stable release) </td> <td> (None) </td> <td> (None) </td> </tr> </table> <p> To find out what's changed, read the <a href="main/Changes">change log</a>. <a name="sample"></a> <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> <a name="lib"></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. <a name="porting"> <h3>Porting</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. <p> P4Ruby has been built on at least the following platforms: </p> <ul> <li> Linux (gcc 2.9x) - use p4api.tar from <b>bin.linux24x86</b> </li> <li> Linux (gcc 3.x/4.x) - use p4api.tar from <b>bin.linux26x86</b>, or <b>bin.linux26x86_64</b> if you're on a 64-bit Linux (and your Ruby is built as a 64-bit binary). </li> <li> FreeBSD 4 (gcc 2.9x) </li> <li> Solaris 2.6, 2.7, 2.8, 10 </li> <li> Windows (Visual C++) </li> </ul> <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> <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> </p> <a name="credits"></a> <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! |