P4Ruby Frequently Asked Questions
---------------------------------

CONTENTS

1. Building P4Ruby

    - Which version of the Perforce API should I use?
    - The build worked but P4Ruby fails with 'unresolved symbol' errors...

2. Using P4Ruby

    - I get syntax errors or bad results when I pass arguments to commands


Building P4Ruby
---------------

Q: Which version of the Perforce API should I use?

A: The one that matches your platform. You should consider (a) the operating
   system (b) the CPU architecture (x86/AMD64/sparc etc) and (c) the compiler
   version. 
   
   Most Perforce builds use gcc, but gcc2 is not compatible with gcc3 so if
   your platform uses gcc3 you must use a Perforce API built with gcc3 and
   vice versa.

Q: The build worked but P4Ruby fails with 'unresolved symbol' errors like 
   this:

    ./P4.so: ./P4.so: undefined symbol: _ZN10ClientUser7MessageEP5Error - ./P4.so (LoadError)
	    from ./lib/P4.rb:112
	    from test.rb:4:in `require'
	    from test.rb:4

A: There are two primary causes of this type of failure:

	- Use of the wrong Perforce API build
	- Incorrect compiler flags when used with the right Perforce API

    The former is MUCH more common, so please check that first. Make sure
    that you're using an API build compiled with gcc3 if your platform uses
    gcc3. Make sure that you're using an API build compiled with gcc2 if
    your platform uses gcc2.

    If that's not it, then it could be a bug in the p4conf.rb script. Some 
    platforms (more and more of them) require us to add 

    	-Dconst_char='const char' 

    to the compiler options. Some unresolved symbol errors occur either when
    this flag IS added when it shouldn't be, or ISN'T added when it should be.

    Send me (tony@smee.org) the output of the following commands on your
    machine if this affects you:

    	ruby -rrbconfig -e 'puts Config::CONFIG[ "target_os" ]'
    	ruby -rrbconfig -e 'puts Config::CONFIG[ "target_cpu" ]'
    	ruby -rrbconfig -e 'puts RUBY_PLATFORM

    And also, please tell me EXACTLY which version of the Perforce API you're
    using.


Using P4Ruby
------------
Q: I get syntax errors or bad results when I pass arguments to commands like
   this:

	p4.run_sync( "fileA fileB fileC" )

A: Both Perforce and P4Ruby support filenames with spaces in them. Have you 
   really got a file called 'fileA fileB fileC'? Probably not. Try:

  	p4.run_sync( "fileA", "fileB", "fileC" )

   instead. Or, if you prefer it, you can use Ruby's %w{} operator to do
   the quoting for you:

   	p4.run_sync( %w{ fileA fileB fileC } )

   The same is true for commands like:

   	p4.run_sync( "-f fileA" )	# WRONG!!!

   Instead you should use:

   	p4.run_sync( "-f", "fileA" )	# RIGHT!!!