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.
On this page:
Prerequisites
-
Ensure your machine meets the system requirements. For information, see System Requirements and Release Notes.
-
P4 API for C/C++ is required. If you do not have P4 API for C/C++, see Get P4 API for C/C++.
-
-
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++
-
To download P4 API for C/C++ for Windows, go to the Perforce website.
-
Ensure you download a version that matches:
-
Your version of Windows (for example, Windows x86).
-
Your version of OpenSSL.
-
-
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.
gem --version. To install P4 API for Ruby using gem, follow these steps:
-
Open the command prompt.
-
Install P4 API for Ruby using the following command:
gem install p4ruby -
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. -
(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.
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.
-
If you do not have Bundler, download it from the Bundler website.
-
Using Bundler, run the following:
gem 'p4ruby', '~> 2020.1' -
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:
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:
-
Open Command Prompt and navigate to your script folder:
cd c:\p4ruby -
Run the following:
ruby test_p4.rb -
If P4 API for Ruby successfully connects, server information will be output to the terminal.