CUPS provides two libraries that interface with the different parts of the printing system. The "cups" library provides all of the common application and filter functions while the "cupsimage" library provides all of the imaging functions used in raster printer drivers. The "cups" library functions are accessed by including the <cups/cups.h> header, while "cupsimage" functions are found in the <cups/raster.h> header.

Compiling Programs

The CUPS libraries can be used from any C, C++, or Objective C program. The method of compiling against the libraries varies depending on the operating system and installation of CUPS. The following sections show how to compile a simple program (shown below) in two common environments.

The following simple program lists the available printers on the system:

#include <stdio.h>
#include <cups/cups.h>

int main(void)
  int i;
  cups_dest_t *dests, *dest;
  int num_dests = cupsGetDests(&dests);

  for (i = num_dests, dest = dests; i > 0; i --, dest ++)
    if (dest->instance)
      printf("%s/%s\n", dest->name, dest->instance);

  return (0);

Compiling with Xcode

In Xcode, choose New Project... from the File menu, then select the Standard Tool project type under Command Line Utility. Click Next and choose a project directory. Click Next to create the project.

In the project window, double-click on the Targets group and control-click on the simple target to show the context menu. Choose Existing Framework... from the Add submenu. When the file chooser sheet appears, press the / key and enter "/usr/lib". Scroll down the file list and select the libcups.dylib file. Click the Add button in the file chooser and attributes sheets.

In the project window, double-click on the main.c source file. Replace the template source code with the listing above and save it. Click the Build and Go button to build the sample program and run it.

Compiling with GCC

From the command-line, create a file called sample.c using your favorite editor and then run the following command to compile it with GCC and run it:

gcc -o simple `cups-config --cflags` simple.c `cups-config --libs`

The cups-config command provides the compiler flags ("cups-config --cflags") and libraries ("cups-config --libs") needed for the local system.

Where to Go Next

If you are developing a print filter, driver, or backend, see the Filter and Backend Programming guide. Raster printer driver developers should also read the Raster API reference.