All the declarations needed for using the PPL's C interface (preprocessor symbols, data types, variables and functions) are collected in the header file ppl_c.h. This file, which is designed to work with pre-ANSI and ANSI C compilers as well as C99 and C++ compilers, should be included, either directly or via some other header file, with the directive

#include <ppl_c.h>

If this directive does not work, then your compiler is unable to find the file ppl_c.h. So check that the library is installed (if it is not installed, you may want to make install, perhaps with root privileges) in the right place (if not you may want to reconfigure the library using the appropriate pathname for the –prefix option); and that your compiler knows where it is installed (if not you should add the path to the directory where ppl_c.h is located to the compiler's include file search path; this is usually done with the -I option).

The name space of the PPL's C interface is PPL_* for preprocessor symbols, enumeration values and variables; and ppl_* for data types and function names. The interface systematically uses opaque data types (generic pointers that completely hide the internal representations from the client code) and provides all required access functions. By using just the interface, the client code can exploit all the functionalities of the library yet avoid directly manipulating the library's data structures. The advantages are that (1) applications do not depend on the internals of the library (these may change from release to release), and (2) the interface invariants can be thoroughly checked (by the access functions).

Note: All functions taking as input argument an opaque pointer datatype assume that such an argument is actually referring to a valid PPL object. For instance, a function with an argument having type ppl_MIP_Problem_t will expect a valid MIP_Problem object, previously initialized by calling, e.g., ppl_new_MIP_Problem. If that is not the case (e.g., if a null pointer is passed in), the behavior is undefined.

The PPL's C interface is initialized by means of the ppl_initialize function. This function must be called before using any other interface of the library. The application can release the resources allocated by the library by calling the ppl_finalize function. After this function is called no other interface of the library may be used until the interface is re-initialized using ppl_initialize.

Any application using the PPL should make sure that only the intended version(s) of the library are ever used. The version used can be checked at compile-time thanks to the macros PPL_VERSION_MAJOR, PPL_VERSION_MINOR, PPL_VERSION_REVISION and PPL_VERSION_BETA, which give, respectively major, minor, revision and beta numbers of the PPL version. This is an example of their use:

#if PPL_VERSION_MAJOR == 0 && PPL_VERSION_MINOR < 6
# error "PPL version 0.6 or following is required"
#endif

Compile-time checking, however, is not normally enough, particularly in an environment where there is dynamic linking. Run-time checking can be performed by means of the functions ppl_version_major, ppl_version_minor, ppl_version_revision, and ppl_version_beta. The PPL's C interface also provides functions ppl_version, returning character string containing the full version number, and ppl_banner, returning a string that, in addition, provides (pointers to) other useful information for the library user.

All programs using the PPL's C interface must link with the following libraries: libppl_c (PPL's C interface), libppl (PPL's core), libgmpxx (GMP's C++ interface), and libgmp (GMP's library core). On most Unix-like systems, this is done by adding -lppl_c, -lppl, -lgmpxx, and -lgmp to the compiler's or linker's command line. For example:

gcc myprogram.o -lppl_c -lppl -lgmpxx -lgmp

If this does not work, it means that your compiler/linker is not finding the libraries where it expects. Again, this could be because you forgot to install the library or you installed it in a non-standard location. In the latter case you will need to use the appropriate options (usually -L) and, if you use shared libraries, some sort of run-time path selection mechanisms. Consult your compiler's documentation for details. Notice that the PPL is built using Libtool and an application can exploit this fact to significantly simplify the linking phase. See Libtool's documentation for details. Those working under Linux can find a lot of useful information on how to use program libraries (including static, shared, and dynamically loaded libraries) in the Program Library HOWTO.

For examples on how to use the functions provided by the C interface, you are referred to the directory demos/ppl_lpsol/ in the source distribution. It contains a Mixed Integer (Linear) Programming solver written in C. In order to use this solver you will need to install GLPK (the GNU Linear Programming Kit): this is used to read linear programs in MPS format.