README #8 

			    Perforce for Ruby
			    -----------------

Requirements
------------

You *need* the Perforce API (p4api.tar) from the Perforce FTP site. The URL
is:
	ftp://ftp.perforce.com/pub/perforce

or 
	http://www.perforce.com/downloads/perforce

NOTE TO GCC USERS: If you're using gcc3, please make sure you use a Perforce
API build compiled with gcc3. Using the gcc2 versions won't work. For Linux
users this means you should NOT use the 'bin.linux24x86' builds.

Building
--------

To build P4Ruby, use the p4conf.rb script to build a makefile and then
use your platform's 'make' tool to do the actual build. You must have
downloaded and unpacked the Perforce API first.

Usage:
	ruby p4conf.rb --apidir <path> [ --apibuild <build> ] [ --gccver 2|3 ]

Where:

	--apidir <path>		- is the path to the Perforce API

	--apibuild <build>	- is the build identifier of the Perforce API.
				  For example:

				  	ntx86		- Windows NT
					linux24x86	- Linux w/ gcc 2.95
					linux3x86	- Linux w/ gcc 3.x
					linux26amd64	- Linux on AMD 64-bit

				  This is the same as the directory name from
				  which you downloaded the Perforce API 
				  (without the leading 'bin.' obviously)

				  Most people won't need to use this as the
				  script tries to detect this automatically.
	
	--gccver 2|3		- Which version of gcc you're using. Some
				  platforms (Cygwin/Darwin) install both
				  gcc2 and gcc3 and if you want to use gcc2
				  you have to use a different command line. 

				  Using --gccver=2 allows you to do this.

UNIX Builds:

    Unpack the Perforce API into a new directory - but *NOT* in the same 
    directory as this extension (mkmf won't like it). 

    Then run:

	ruby p4conf.rb 	--apidir <path to api> 
	make
	make install

    For the last step, you'll probably need to be root.

Windows Builds:

    You will need Visual Studio to build P4/Ruby as mkmf generates nmake
    compatible makefiles.

    Unpack the Perforce API into a new directory - but *NOT* in the same 
    directory as this extension (mkmf won't like it). 

    Then run:

	ruby p4conf.rb 	--apidir <path to api> 
	nmake
	nmake install
	

Cygwin Builds:

    Do NOT attempt to build the P4Ruby for use with Cygwin's Ruby build 
    without using the Cygwin version of the Perforce API! Many people think
    they can use the Windows build of the API, but it won't work, so don't
    waste your time.

Troubleshooting
---------------

See the FAQ
# Change User Description Committed
#8 5111 Tony Smith Make P4Ruby's build script support the const_char macro definition
on those platforms that need it (Solaris >= 2.7 and Linux on AMD64
primarily). If we ever port P4Ruby to LinuxIA64 we'll need to
add support for that too.

With this change p4conf.rb tries harder to determine the O/S name
and version, but it's unlikely to get it right all the time. So
there's also a new '--apibuild' flag to p4conf.rb that allows
the user to override the detected platform with an explicit
configuration. Most people won't have to use it, but it'll be
there for those that need it.

I've also updated the README with the new build procedure, and
added a FAQ document for the most common questions.
#7 4833 Tony Smith Bring P4Ruby's README file up to date.
#6 4589 Tony Smith Update P4Ruby to support the new SetProg() method in the 2004.2 API.
Whilst the new 'P4#prog=' method is always available, it's only
functional if P4Ruby is built with a 2004.2 or later API.

The build system got a bit of tidying up to support this change and
the API version is now detected automatically if possible. I've also
removed the --apilibdir and --apiincludedir flags as they complicate
matters and I never use them and I don't believe anyone else does
either.

There are also some minor doc formatting tweaks to go along with
the added documentation for prog=.
#5 3541 Tony Smith Porting change.
Now builds under Cygwin with only a few filthy
hacks. New undoc'd --gccver=2 flag allows Cygwin users to build
P4Ruby using the gcc-2 package rather than the default compiler
which is currently gcc 3.2.3. They have to do this because the
Perforce API is not yet available in a gcc-3 version for Cygwin.
#4 2388 Tony Smith Rework p4conf.rb script to improve the build process.
There are now
two mandatory parms and if you omit them you will be prompted for
their values.

--apidir <dir>         - Path to the Perforce API
--apiver <string>    - API version string (e.g. 2002.2)

I've also renamed the .so file from "P4api.so" to just P4.so
and I've improved the self identification code to include the
build flags and the API version to help with diagnosis.
#3 2378 Tony Smith Tweaks to readme file.
#2 1326 Tony Smith Remove outdated reference to lack of docs on P4/Ruby.
#1 1015 Tony Smith First cut of Perforce bindings for the Ruby scripting language.
Similar functionality to the Perl API stuff, but "rubyfied".
Supports error reporting via exceptions, and presents tagged
output and parsed forms as hash structures, with nested arrays
where required.

Still early days so the docs are thin on the ground. See the
example.pl for a brief guide.

Built with Ruby 1.6.4 on Linux.  May still be some memory
management issues as the Ruby Garbage Collection API has
changed a little since the docs I've got and I've just
dodged garbage collection for now.

Not indexing this just yet.