The Developer's Guide to Gutenprint
<<< Previous | Using libgutenprint | Next >>>

# 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`.

<<< Previous | Home | Next >>>
Linking with libgutenprint | Up | Reporting Bugs