Installing P4 API for Ruby

There are several ways to install P4 API for Ruby:

In each case, ensure you have met all the criteria of the prerequisites

Prerequisites

  • Ensure your machine meets the system requirements. For information, see System Requirements and Release Notes.

  • The latest version of P4 API for Ruby requires Ruby 3.2 and above. To check which version of Ruby you have, run the following command:

    ruby -v

Install P4 API for Ruby using gem

The easiest way to install P4 API for Ruby is to use gem.

The installation package gem is included with Ruby. To check if gem is installed, run gem --version.

To install P4 API for Ruby using gem, follow these steps:

  1. Open a terminal or command prompt.

  2. (Optional) Upgrade gem using the following command:

    gem update --system

  3. Install P4 API for Ruby using the following command:

    gem install p4ruby

  4. If P4 API for Ruby is installed correctly, you will see the following output in the terminal or command prompt:

    Successfully installed p4ruby-<VERSION>

    Where <VERSION> is the installed version of P4 API for Ruby.

Install P4 API for Ruby on macOS or Linux

If you are installing P4 API for Ruby on macOS or Linux, the P4 API for Ruby gem must be compiled locally against your Ruby installation. If you can build the core Ruby distribution locally, you should be able to install P4 API for Ruby without issues.

This method requires P4 API for C/C++. Download P4 API for C/C++ from the Perforce website and make a note of its location.

The P4 API for C/C++ version must match the major and minor version of the P4 API for Ruby gem.

If you are manually specifying the P4 API for C/C++ location using --with-p4api-dir, ensure the headers and libraries are compatible with your Ruby version and platform.

The preferred installation method uses Bundler.

  1. If you do not have Bundler, download it from the Bundler website.

  2. Using Bundler, run the following:

    gem 'p4ruby', '~> 2020.1'

  3. Then run:

    bundle install --with-p4api-dir=<DIR>

    Where, <DIR> is path to your local P4 API for C/C++ installation.

Install P4 API for Ruby from source

The official version of P4 API for Ruby exists as source on GitHub.

Instructions for building are in the BUILD.md file, which is also hosted on GitHub.

Sample script to test P4 API for Ruby

To further check if P4 API for Ruby has been installed correctly, create a simple script that connects to your server.

Create test_p4.rb in a folder (for example, C:\p4ruby) with the following code:

Copy 
require 'P4'

p4 = P4.new
p4.user   = 'user.name'     # enter your username
p4.client = 'work_space'    # enter your workspace
p4.port   = 'perforce:1666' # enter your hostname

p4.connect
puts p4.run('info')  # prints Perforce server info
p4.disconnect

To run the script:

  1. Open Command Prompt and navigate to your script folder:

    cd c:\p4ruby

  2. Run the following:

    ruby test_p4.rb

  3. If P4 API for Ruby successfully connects, server information will be output to the terminal.