Building with Jam

Jam is a build tool, similar in its role to the more familiar make. Jamfiles are to jam as makefiles are to make.

Jam is an Open Source project sponsored by Perforce Software, Inc.. Jam documentation, source code, and links to precompiled binaries are available from the Jam product information page at:

http://www.perforce.com/documentation/jam

The P4API distribution contains the necessary header files (*.h) and libraries (libclient.a, librpc.a, libsupp.a, libp4sslstub.a) required to compile and link a client application. The distribution also includes a sample application in C++, p4api.cc.

In general, the process is similar to most APIs: compile your application sources, then link them with the API libraries. The precise steps needed vary somewhat from platform to platform.

The sample application p4api.cc is a portable, minimal Helix Core Server application, which we can use as an example. For purposes of this example, assume a Linux system.

Compile and link p4api.cc as follows:

$ cc -c -o p4api.o -D_GNU_SOURCE -O2 -DOS_LINUX -DOS_LINUX24 \
> -DOS_LINUXX86 -DOS_LINUX24X86 -I. -Imsgs -Isupport -Isys p4api.cc

$ gcc -o p4api p4api.o libclient.a librpc.a libsupp.a libp4sslstub.a

The preprocessor definitions (-Ddefinition) vary from platform to platform.

In order to build the example across a wide variety of platforms, the API distribution also contains two "Jamfiles" (Jamrules and Jamfile) that describe to how to build the sample application on each platform.

Building the sample application

Once you have Jam on your system, you can use it to build the p4api application. On some platforms, jam needs an extra hint about the operating system version. For instance, on RedHat Linux 7.1, with a 2.4 linux kernel, use OSVER=24:

$ jam
Set OSVER to 42/52 [RedHat M.n], or 22/24 [uname -r M.n]

$ uname -r
2.4.2-2

$ jam -s OSVER=24
...found 121 target(s)...
...updating 2 target(s)...
C++ p4api.o
Link p4api
Chmod1 p4api
...updated 2 target(s)...

$ p4api info
User name: you
Client name: you:home:sunflower
Client host: sunflower
Client root: /home/you
Current directory: /home/you/tmp/p4api
Client address: 207.46.230.220:35012
Server address: sunflower:1674
Server root: /home/p4/root
Server date: 2009/09/24 12:15:39 PDT
Server version: P4D/LINUX22X86/2009.1/192489 (2009/04/12)
Server license: Your Company 10 users (expires 2010/02/10)
Server license-ip: 10.0.0.2

As shown in the example above, jam does not, by default, show the actual commands used in the build (unless one of them fails). To see the exact commands jam generates, use the -o file option. This causes jam to write the updating actions to file, suitable for execution by a shell.

To illustrate; first, invoke jam clean to undo the build:

$ jam -s OSVER=42 clean
  ...found 1 target(s)...
  ...updating 1 target(s)...
  Clean clean
  ...updated 1 target(s)...

Then use jam -o build_sample to create the build file:

$ jam -s OSVER=42 -o build_sample
  ...found 121 target(s)...
  ...updating 2 target(s)...
  C++ p4api.o
  Link p4api
  Chmod1 p4api
  ...updated 2 target(s)...

$ cat build_sample

cc -c -o p4api.o -O2 -DOS_LINUX -DOS_LINUX42 -DOS_LINUXX86 \
-DOS_LINUX42X86 -I. -Imsgs -Isupport -Isys p4api.cc
gcc -o p4api p4api.o libclient.a librpc.a libsupp.a libp4sslstub.a
chmod 711 p4api

The generated build_sample can then be executed by a shell:

/bin/sh build_sample

to produce the executable, which you can test by running p4api info or most other Helix Core Server commands:

$ p4api changes -m 1

Change 372 on 2002/09/23 by you@you:home:sunflower 'Building API'

As you can see, p4api is a usable full-featured command line Helix Core Server client (very similar to the p4 command). The example’s functionality comes from the default implementation of the ClientUser class, linked from the libclient.a library and the rest of the library code, for which source code is not included. The source for the default implementation is provided in the P4API distribution as clientuser.cc.