Installing P4 API for Ruby

This page describes how to install P4 API for Ruby and its required dependencies.

P4 API for Ruby requires the P4 API for C/C++ and a compatible Ruby toolchain.

These prerequisites must be installed before running gem install P4 API for Ruby.

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

Get P4 API for C/C++

  1. To download P4 API for C/C++ for Windows, go to the Perforce website.

  2. Ensure you download a version that matches:

    • Your version of Windows (for example, Windows x86).

    • Your version of OpenSSL.

  3. Extract P4 API for C/C++ in a known location, for example C:\p4api.

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 the command prompt.

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

    gem install p4ruby

  3. 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.

  4. (Optional )To check P4 API for Ruby has been installed, run the following:

    ruby -rP4 -e "puts P4.identify"

    If successfully installed, the version of P4 API for Ruby is output to the terminal.

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.