Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

C/C++ API Documentation | 2025.1

# 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 P4 API for C/C++ 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 P4 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`:

Copy

    $ 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:

Copy

    $ 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:

Copy

    $ 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 P4 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 P4 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 P4 API for C/C++ distribution as `clientuser.cc`.

Your search for returned results