Perforce Public Knowledge Base - Using and building the Perforce C++ API with Make on Cygwin and MacOS X
Perforce Software logo
Reset Search
 

 

Article

Using and building the Perforce C++ API with Make on Cygwin and MacOS X

« Go Back

Information

 
Problem

The Perforce C++ API (P4API) enables you to create client programs that interact with end users, send commands to a Perforce server and process data returned from the server. This API is a programmatic interface, and does not send commands directly to the server. The P4API enables programmers to implement functionality and customizations not available in existing Perforce clients. This article demonstrates using the P4API on Cygwin and MacOS X to create two simple C++ programs.

Solution

Why do I need P4API?

With the P4API you can manipulate the output of the Perforce command-line client by means of scripts written in Perl, Python, Ruby, and so on. Through these scripts, each P4 command corresponds to a connection and disconnection request to the P4D.  The written script is simply a wrapper around the P4 command. With the P4API we can batch P4 commands while having a single connection to the server. This lessens the load on the server and reduces network traffic to a minimum.

Installing P4API

Download p4api.tgz file from ftp.perforce.com.  For example, a build pre-configured for Cygwin (or Mac OS X) from our FTP site.

ftp.perforce.com/perforce/r09.2/bin.cygwinx86/p4api.tgz (or /r09.2/bin.darwin80u/p4api.tgz )

Run

tar -zxvf p4api.tgz
to uncompress the archive. The P4API contains three directories: /include/, /lib/, and /sample/.
 

Headers under "include/p4" directory:

Under the /include/ directory, you will find a /p4/ directory which contains headers needed for inclusion by the defined class or classes. The headers of interest are clientapi.h, clientuser.h, and filesys.h, which will in general be used by most P4API client programs.

Libraries under "lib" directory:

Under the "lib" directory, you will find three files: libclient.a, librpc.a, and libsupp.a. These libraries are a collection of developer defined functions  Common errors compiling the derived APIs are due to the inaccessibility of these libraries through incorrectly specified paths or the inability to include these libraries because of architectural differences.

Files under "sample" directory:

There are five files under the "sample" directory: Jamfile.api, Jamrules, Version, clientuser.cc, and p4api.cc.

Building the client program using Make

When using /Make/ to build a client executable, the Jamfile.api, Jamrules, and Version files are not required.
  •   A "Makefile" for use under Cygwin
SOURCES = p4api.cc
LIBPATH = /<path_to_p4_c++_api>
INCLUDES = -I$(LIBPATH)/include/p4
OBJECTS = $(SOURCES:.cc=.o)
LIBRARIES = $(LIBPATH)/lib/libclient.a $(LIBPATH)/lib/librpc.a $(LIBPATH)/lib/libsupp.a
BINARY = p4api
RM = RM -f

C++ = g++
C++FLAGS = -c -g -D__cygwin__
LINK = g++
LINKFLAGS =

.cc.o :
	$(C++) $(C++FLAGS) $< $(INCLUDES)

$(BINARY): $(OBJECTS)
	$(LINK) -o $(BINARY) $(OBJECTS) $(LIBRARIES)

clean:
	- $(RM) $(OBJECTS) $(BINARY).exe
  • A "Makefile" for use under MacOS X 10.5
SOURCES = p4api.cc
LIBPATH = /<path_to_p4_c++_api>
INCLUDES = -I$(LIBPATH)/include/p4
OBJECTS = $(SOURCES:.cc=.o)
LIBRARIES = $(LIBPATH)/lib/libclient.a $(LIBPATH)/lib/librpc.a $(LIBPATH)/lib/libsupp.a
BINARY = p4api
RM = RM -f

C++ = g++
C++FLAGS = -c -g -fvisibility-inlines-hidden
LINK = g++
LINKFLAGS =

.cc.o :
	$(C++) $(C++FLAGS) $< $(INCLUDES)

$(BINARY): $(OBJECTS)
	$(LINK) -o $(BINARY) $(OBJECTS) $(LIBRARIES)

clean:
	- $(RM) $(OBJECTS) $(BINARY).exe
  • Build the client program by running "Makefile"

Example P4API programs

The following are examples of P4API programs.
  •   A simple connection to the server.
#include "clientapi.h"

int main(int argc, char *argv[]) {
   
   ClientApi client;
   Error e;

   client.init(&e);

   if(e.Test()) {
	printf("Failed to connect:\n");
   }

   printf("Connected OK\n");

   return 0;
}
#include "clientapi.h"

int main(int argc, char *argv[]) {

   ClientApi client;  //Create client object
   ClientUser ui;     //Create an object for P4

   char file[] = "test.txt";  //character string
   char *filep = &file[0];    //Has the address
			      //in the beginning of the string

   Error e;

   client.init(&e);

   if(e.Test()) {	     //Is there an error?
	printf("Failed to connect:\n");
   }

   client.SetArgv(1, &filep);  //test.txt is set as argument
   client.Run("filelog", &ui); //same as "p4 filelog test.txt"

   client.Final(&e);
}

The example programs use three classes: ClientApi, ClientUser, and Error. The ClientApi class has methods to establish and terminate the connection to the Perforce Server. The ClientUser class is used for client-side input and output. The implemented methods return output from the server to the user after a command is invoked. Error class is used to store error messages.

There are other API classes available. For more information, please see the C/C++ API User's Guide.
Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255