Integrating libgimpprint
************************

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

gimpprint-config
================

Depending on the setup of the computer system GIMP-Print 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 libgimpprint may vary. To make it simple to determine what these are on any given system, the script gimpprint-config was created. It's job is to output the correct parameters for the setup on your system. The following options are available:

     roger@whinlatter:~/gimpprint/devel$ gimpprint-config --help
     Usage: gimpprint-config [OPTIONS] [LIBRARIES]
     Options:
             [--prefix[=DIR]]
             [--exec-prefix[=DIR]]
             [--version]
             [--libs]
             [--cflags]
     Libraries:
             gimpprint

The --prefix and --exec-prefix options are only needed if the installed locations of parts of GIMP-Print are different from the configured locations. These should never be needed if GIMP-Print was properly configured and installed.

The installed version of GIMP-Print can be obtained with the --version option:

     roger@whinlatter:~/gimpprint/devel$ gimpprint-config --version
     VERSION

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

     roger@whinlatter:~/gimpprint/devel$ gimpprint-config --cflags

In this case, there are no special CFLAGS required to compile programs.

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

     roger@whinlatter:~/gimpprint/devel$ gimpprint-config --libs
     -L/usr/lib -lgimpprint -lm

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

     gcc `gimpprint-config --cflags` -c prog.c
     gcc `gimpprint-config --libs` -o prog prog.o

However, this is not the way it it typically used. Normally it is used in a Makefile (see make) or by an m4 macro in a configure script (see autoconf).

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:

     GIMPPRINT_VERSION = $(shell gimpprint-config --version)
     GIMPPRINT_CFLAGS = $(shell gimpprint-config --cflags)
     GIMPPRINT_LIBS = $(shell gimpprint-config --libs)

How you choose to use these variables is entirely up to you. See GNU make (make), for more information.

autoconf
========

The autoconf program produces a Bourne shell script called configure from a template file called configure.in. configure.in 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 GNU autoconf (autoconf), for more information.

GIMP-Print provides an m4 macro, AM_PATH_GIMPPRINT, suitable for use in a configure.in. It defines the environment variables GIMPPRINT_CFLAGS, GIMPPRINT_LIBS and GIMPPRINT_CONFIG. You can optionally specify a minimum version of the library to use, and shell script to run if the test suceeds or fails.

 -- Macro: AM_PATH_GIMPPRINT ([MINIMUM-VERSION [, ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
     Check for an installed version of GIMP-Print greater than or equal to MINIMUM-VERSION.

     ACTION-IF-FOUND is a list of shell commands to run if the check for the library succeeds; ACTION-IF-NOT-FOUND is a list of shell commands to run if the check fails.

     The macro sets the following environment variables: GIMPPRINT_CFLAGS, GIMPPRINT_LIBS and GIMPPRINT_CONFIG. It also will substitute them into any Makefile.in you specify in AC_OUTPUT because it calls AC_SUBST for each of them. However, you will probably be using automake to generate your Makefile.in files (see automake).

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 script which uses the AM_PATH_GIMPPRINT macro (there is little point in not using it!).

It is highly recommeded 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 files 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 files, 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 GNU automake (automake), for more information.

Because AM_PATH_GIMPPRINT calls AC_SUBST to substitute GIMPPRINT_CFLAGS, GIMPPRINT_LIBS and GIMPPRINT_CONFIG, 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 prog from a file prog.c. This is how one might build write a Makefile.am to do this:

     AUTOMAKE_OPTIONS = 1.4 gnu
     MAINT_CHARSET = latin1

     @SET_MAKE@

     CFLAGS = @CFLAGS@

     INCLUDES = @INCLUDES@ $(GIMPPRINT_CFLAGS)

     bin_PROGRAMS = prog
     prog_SOURCES = prog.c
     prog_LDADD = $(GIMPPRINT_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.in and the use of AC_SUBST to substitute CFLAGS and INCLUDES where @CFLAGS@ and @INCLUDES@ are found in the file, respectively.