Quick start P4 API for Perl on Windows

Before you begin

Ensure you have the following:

  • Access to a working P4 Server.

  • The server and port values for P4 Server.

  • The username for your P4 user.

  • The name of the workspace that contains the files you want to check out, edit, and commit.

  • (Optional) P4V, to verify that files have been added to a changelist.

  • Strawberry Perl version 5.26, 5.30, 5.34, or 5.38.

Important compatibility check

P4 API for Perl is only compatible with the following versions of Perl:

  • 5.26

  • 5.30

  • 5.34

  • 5.38

If you are using a version of Perl later than 5.38, you must downgrade to a supported version to use P4 API for Perl. Sorry!

Download a compatible version of Strawberry Perl from the official website.

Install P4 API for Perl

The easiest way to install P4 API for Perl is by using the official .exe file.

  1. Download the P4 API for Perl from the Perforce website.

  2. Launch the downloaded .exe file.

    During installation, the installer checks your Perl version. If a compatible version is detected, the installation continues.

  3. In Select Applications, ensure Command-Line Client (P4) is selected and accept the default installation directory.

  4. In Client Configuration, your P4 Server settings should populate automatically. Verify that the following fields are correct:

    • Server - <hostname>:<port-number> for your P4 Server (for example, localhost:1666).

    • User Name - Your P4 username.

  5. Click Install.

To confirm that P4 API for Perl was installed correctly, open a command prompt and run:

perl -MP4 -e "print $P4::VERSION"

If successful, the installed version number will be displayed.

For more information on installing P4 API for Perl (including installing from source), see Installing P4 API for Perl.

Connect the API to P4 Server

Use the following script to connect to P4 Server and view the first five files in a given workspace.

Update the following credentials in the script:

  • P4PORT - Add the server and port to connect to in the format: server:port

  • P4USER - A username for your P4 user.

  • P4CLIENT - The name of the workspace you want to connect to.

Call the script something simple like connect_to_p4.pl

Copy 
#!/usr/bin/perl
use strict;
use warnings;
use P4;

# ---- P4 connection details ----
my $P4PORT   = "localhost:1666";
my $P4USER   = "P4UserName";
my $P4CLIENT = "Perl_Project_main";

#  Create a new P4 API object
my $p4 = P4->new();
$p4->SetPort($P4PORT);
$p4->SetUser($P4USER);
$p4->SetClient($P4CLIENT);

eval {
    # Connect to the P4 Server
    $p4->Connect();

    # Run 'p4 info' to confirm the connection
    my @info = $p4->Run("info");
    print "Connection successful.\n";
    print "Connected to P4 Server at $info[0]->{serverAddress}\n";
    print "Workspace: $P4CLIENT\n\n";

    # List files currently in the workspace
    my @files = $p4->Run("have");

    if (!@files) {
        print "No files are currently synced in this workspace.\n";
    } else {
        print "First 5 files in the workspace:\n";

        my $count = 0;
        foreach my $f (@files) {
            last if $count == 5;
            
            # Print depot path, revision, and local file path
            print " - $f->{depotFile}";
            print "#$f->{haveRev}";
            print " -> $f->{clientFile}\n";

            $count++;
        }
    }
    # Disconnect cleanly from the server
    $p4->Disconnect();
};

# Print any P4 errors if the connection fails
if ($@) {
    print "Failed to connect to the P4 Server.\n";
    print join("\n", $p4->Errors());
}

To run the script:

  1. Open a terminal and navigate to the folder containing the script.

  2. Run perl connect_to_p4.pl (If you have given the script a different name, use that name).

  3. Check the output.

This lists up to five files that are currently synced to the workspace.

If you receive any errors when connecting to the P4 Server, see Troubleshooting.

Check out a file

The following script will:

  • Connect to P4 Server with your credentials (user and workspace).

  • Create a pending changelist with a simple description.

  • Open the target file for edit in that changelist.

  • Return a brief summary of what has been done.

    • This returns a changelist number. This number is needed when submitting the file.

  • Disconnect from the P4 Server cleanly.

This script disconnects from the P4 Server because opening a file for edit is a one‑time server operation, not a live session. When a file is checked out it remains open until you submit or revert with no connection required.

Update the following credentials in the script:

  • P4PORT - Add the server and port to connect to in the format: server:port

  • P4USER - A username for your P4 user.

  • P4CLIENT - The name of the workspace you want to connect to.

  • DEPOT_FILE - Filepath to the file to edit. For example: //DemoDepot/perl/README.md

Call the script something simple like check_out_file.pl

Copy 
#!/usr/bin/perl
use strict;
use warnings;
use P4;
use POSIX qw(strftime);


# ---- P4 connection details ----
my $P4PORT   = "localhost:1666";
my $P4USER   = "P4UserName";
my $P4CLIENT = "Perl_Project_main";
my $DEPOT_FILE = "//DemoDepot/perl/README.md";  # file to edit


# Create the P4 API object
my $p4 = P4->new();
$p4->SetPort($P4PORT);
$p4->SetUser($P4USER);
$p4->SetClient($P4CLIENT);

eval {
    # Connect to the P4 Server
    $p4->Connect();

    # Create a new pending changelist
    my $change = $p4->FetchChange();
    $change->{Description} =
        "Edit $DEPOT_FILE via P4 Perl (" .
        strftime("%Y-%m-%d %H:%M:%S", localtime) . ")";

    my @saved = $p4->SaveChange($change);

    # Extract the changelist number from the result
    $saved[0] =~ /Change (\d+)/;
    my $cl = $1;

    print "Created changelist $cl\n";

    # Open the existing file for edit in that changelist
    $p4->Run("edit", "-c", $cl, $DEPOT_FILE);
    print "Opened for edit: $DEPOT_FILE (changelist $cl)\n";
    print "Changelist number: $cl\n";

    # Disconnect cleanly
    $p4->Disconnect();
};

if ($@) {
    print "P4 error occurred:\n";
    print join("\n", $p4->Errors());
}

To run the script:

  1. Open a terminal and navigate to the folder containing the script.

  2. Run perl check_out_file.pl (If you have given the script a different name, use that name)

  3. Make a note of the changelist number. You will need this to commit the file.

Your chosen file is now available to edit.

If you have P4V, you will see a new changelist with your selected file.

Commit a file

The following script will:

  • Prompt you for the changelist number.

    • This changelist number was output in the previous section.

  • Connect to the P4 Server

  • Fetch the changelist to ensure it’s pending.

  • Show the current description, then ask you to add any more detail for the changelist description.

  • Submit the changelist and print the result.

  • Disconnect from P4 Server.

Update the following credentials in the script:

  • P4PORT - Add the server and port to connect to in the format: server:port

  • P4USER - A username for your P4 user.

  • P4CLIENT - The name of the workspace you want to connect to.

Call the script something simple like commit_file.pl

Copy 
#!/usr/bin/perl
use strict;
use warnings;
use P4;

# ---- P4 connection details ----
my $P4PORT   = "localhost:1666";
my $P4USER   = "P4UserName";
my $P4CLIENT = "Perl_Project_main";

# ---- Get changelist number ----
my $CL = $ARGV[0];

if (!$CL) {
    print "Enter the changelist number to submit: ";
    $CL = <STDIN>;
    chomp $CL;

    if (!$CL) {
        die "No changelist number provided. Exiting.\n";
    }
}

# Create the P4 API object
my $p4 = P4->new();
$p4->SetPort($P4PORT);
$p4->SetUser($P4USER);
$p4->SetClient($P4CLIENT);

eval {
    # Connect to the P4 Server
    $p4->Connect();

    # Fetch the changelist
    my $change = $p4->FetchChange($CL);

    if (lc($change->{Status}) ne "pending") {
        die "Changelist $CL is not pending (status: $change->{Status})\n";
    }

    # Show current description
    print "Current description:\n";
    print "--------------------\n";
    print $change->{Description} . "\n";

    # Optional submit comment
    print "Add a submit comment (leave blank to keep existing description): ";
    my $note = <STDIN>;
    chomp $note;

    if ($note ne "") {
        $change->{Description} .= "\n\n" . $note;
        $p4->SaveChange($change);
        print "Updated changelist description.\n";
    }

    # Submit the changelist
    $p4->RunSubmit($change);
    print "Submitted changelist $CL\n";

    # Disconnect cleanly
    $p4->Disconnect();
};

if ($@) {
    print "P4 error occurred:\n";
    print join("\n", $p4->Errors());
}

To run the script:

  1. Open a terminal and navigate to the folder containing the script.

  2. Run perl commit_file.pl

  3. When asked, enter the changelist number with the file you want to commit.

  4. (Optional) Enter a changelist description .

Your chosen file has now been committed. If you check P4V, you will no longer be able to see the pending changelist.

Next steps

View the documentation for P4 API for Perl Classes to see what other commands are available when using P4 API for Perl.