# Using libgutenprint

This chapter describes how to write programs that use libgutenprint.

## Code prerequisites

To use libgutenprint with a program, several steps must be taken:

- Include the master libgutenprint header:

      <gimp-print/gimp-print.h>

- Call `stp_init`.

- Link with the libgutenprint library.

The following is a short example program. It does not do anything useful, but it does everything required to link with libgutenprint and call other functions from libgutenprint.

    #include <gimp-print/gimp-print.h>
    int
    main (int argc, char *argv[])
    {
      stp_init();
      return 0;
    }

## Linking with libgutenprint

To link a program with libgutenprint, the option `-lgutenprint` needs to be passed to the compiler when linking. For example, to compile and link `stpimage.c` the following commands would be used:

    $ gcc -c stpimage.c
    $ gcc -o stpimage -lgutenprint stpimage.o

The compiler and linker flags needed may vary depending on the options Gutenprint was configured with when it was built. The `pkg-config` script will give the correct parameters for the local installation.

## Integrating libgutenprint

This section describes how to integrate the compiling and linking of programs using libgutenprint with build scripts. Commonly used systems include `make`, but often `Makefile` files are generated by using tools such as `autoconf` and `automake`.

### `pkg-config`

Depending on the nature of the computer system Gutenprint was installed on, as well as the options passed to `configure` when configuring the package when it was built, the `CFLAGS` and `LIBS` parameters needed to compile and link programs with libgutenprint may vary. To make it simple to determine what these are on any given system, a `pkg-config` datafile was created when Gutenprint was built. `pkg-config` will output the correct parameters for the setup on your system. See the pkg-config(1) manual page for a compete synopsis.

The correct `CFLAGS` to use can be obtained with the `--cflags` option:

    $ pkg-config --cflags gutenprint
    -I/usr/local/include

The correct `LIBS` to use can the obtained with the `--libs` option:

    $ pkg-config --libs gutenprint
    -L/usr/local/lib -lgutenprint -lm -ldl

Lastly, the installed version of Gutenprint can be obtained with the `--version` option:

    $ pkg-config --modversion gutenprint
    4.3.23

The command can be used from the shell by enclosing it in backquotes ‘`’:

    $ gcc `pkg-config --cflags gutenprint` -c stpimage.c
    $ gcc `pkg-config --libs gutenprint` -o
      stpimage stpimage.o

However, this is not the way it it typically used. Normally it is used in a `Makefile` or by an m4 macro in a `configure` script.

### `make`

If you use `make` with your own `Makefile` files, then you are on your own. This manual offers no assistance with doing this. Only the following suggestion is offered, for use with GNU `make`:

    GUTENPRINT_VERSION = $(shell pkg-config --version gutenprint)
    GUTENPRINT_CFLAGS = $(shell pkg-config --cflags gutenprint)
    GUTENPRINT_LIBS = $(shell pkg-config --libs gutenprint)

How you choose to use these variables is entirely up to you. See the GNU `make` manual for more information.

### `autoconf`

The `autoconf` program produces a Bourne shell script called `configure` from a template file called `configure.ac`. `configure.ac` contains both Bourne shell script, and m4 macros. `autoconf` expands the m4 macros into ‘real’ shell script. The resulting `configure` script performs various checks for installed programs, compiler characteristics and other system information such as available headers and libraries. See the GNU `autoconf` manual for more information.

`pkg-config` provides an m4 macro, `PKG_CHECK_MODULES`, suitable for use in a `configure.ac` script. It defines the environment variables required for building libgutenprint-based programs. For example, to set GUTENPRINT_CFLAGS and GUTENPRINT_LIBS:

    PKG_CHECK_MODULES(GUTENPRINT, gutenprint)

### `automake`

The `automake` program can be used to generate `Makefile.in` files suitable for use with a `configure` script generated by `autoconf`. As `automake` requires `autoconf`, this section will assume the use of a `configure.ac` script which uses the `PKG_CHECK_MODULES` macro described above (there is little point in not using it!).

It is highly recommended that you use GNU `autoconf` and `automake`. They will allow you to make your software build on most platforms with most compilers. `automake` makes writing complex `Makefile`'s very easy, by expressing how to build your packages in terms of what files are required to build a project and the installation locations of the files. It imposes a few limitations over using plain `Makefile`'s, such as in the use of conditionals, but these problems are vastly outweighed by the benefits it brings. It also creates many extra targets in the generated `Makefile.in` files such as `dist`, `distcheck`, `clean`, `distclean`, `maintainer-clean` and `tags`, and there are many more more available. See the GNU `automake` manual for more information.

Because `PKG_CHECK_MODULES` calls `AC_SUBST` to substitute `GUTENPRINT_CFLAGS` and `GUTENPRINT_LIBS`, `automake` will automatically set these variables in the `Makefile.in` files it generates, requiring no additional effort on your part!

As in previous examples, we will make a program `stpimage` from `stpimage.c`. This is how one might build write a `Makefile.am` to do this:

    @SET_MAKE@

    AM_CFLAGS = $(GUTENPRINT_CFLAGS)

    bin_PROGRAMS = stpimage
    stpimage_SOURCES = stpimage.c
    stpimage_LDADD = $(GUTENPRINT_LIBS)

    MAINTAINERCLEANFILES = Makefile.in

That's all there is to it! Please note that this example also requires the macro `AC_PROG_MAKE_SET` to be used in `configure.ac`.