@node Integrating libgimpprint, Functions, Using libgimpprint, Top
@chapter Integrating libgimpprint
@cindex integrating

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

@menu
* gimpprint-config::            Getting the correct compiler and linker flags
* make::                        Normal makefiles
* autoconf::                    Macro to automatically check for libgimpprint
* automake::                    Automatically defined variables to use
@end menu


@node gimpprint-config, make, , Integrating libgimpprint
@section @command{gimpprint-config}
@pindex gimpprint-config

Depending on the setup of the computer system GIMP-Print was installed on, as
well as the options passed to @command{configure} when configuring the
package when it was built, the @env{CFLAGS} and @env{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
@command{gimpprint-config} was created. It's job is to output the
correct parameters for the setup on your system. The following options
are available:

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

The @option{--prefix} and @option{--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
@option{--version} option:

@example
roger@@whinlatter:~/gimpprint/devel$ gimpprint-config --version
@value{VERSION}
@end example

The correct @env{CFLAGS} to use can be obtained with the @option{--cflags}
option:

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

@end example

In this case, there are no special @env{CFLAGS} required to compile programs.

The correct @env{LIBS} to use can the obtained with the @option{--libs} option:

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

The command can be used from the shell by enclosing it in backquotes @samp{`}:

@example
gcc `gimpprint-config --cflags` -c prog.c
gcc `gimpprint-config --libs` -o prog prog.o
@end example

However, this is not the way it it typically used. Normally it is used in a
@file{Makefile} (@pxref{make}) or by an @command{m4} macro in a @command{configure}
script (@pxref{autoconf}).


@node make, autoconf, gimpprint-config, Integrating libgimpprint
@section @command{make}
@pindex make

If you use @command{make} with your own @file{Makefile} files, then you are on
your own. This manual offers no assistance with doing this. Only the following
suggestion is offered:

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

How you choose to use these variables is entirely up to you. @inforef{Top, GNU
make, make}, for more information.


@node autoconf, automake, make, Integrating libgimpprint
@section @command{autoconf}
@pindex autoconf
@cindex m4 macros

The @command{autoconf} program produces a Bourne shell script called
@file{configure} from a template file called @file{configure.in}.
@file{configure.in} contains both Bourne shell script, and @command{m4} macros.
@command{autoconf} expands the @command{m4} macros into `real' shell script.
The resulting @file{configure} script performs various checks for installed
programs, compiler characteristics and other system information such as
available headers and libraries. @inforef{Top, GNU autoconf, autoconf}, for
more information.

GIMP-Print provides an @command{m4} macro, @code{AM_PATH_GIMPPRINT}, suitable for
use in a @file{configure.in}. It defines the environment variables
@env{GIMPPRINT_CFLAGS}, @env{GIMPPRINT_LIBS} and @env{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.

@defmac AM_PATH_GIMPPRINT (@r{[}@var{minimum-version} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]]})
Check for an installed version of GIMP-Print greater than or equal to
@var{minimum-version}.

@var{action-if-found} is a list of shell commands to run if the check
for the library succeeds; @var{action-if-not-found} is a list of
shell commands to run if the check fails.

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

@end defmac

@node automake, , autoconf, Integrating libgimpprint
@section @command{automake}
@pindex automake

The @command{automake} program can be used to generate @file{Makefile.in} files
suitable for use with a @file{configure} script generated by
@command{autoconf}.  As @command{automake} @emph{requires} @command{autoconf},
this section will assume the use of a @file{configure} script which uses the
@code{AM_PATH_GIMPPRINT} macro (there is little point in @emph{not} using it!).

It is highly recommeded that you use GNU @command{autoconf} and
@command{automake}. They will allow you to make your software build on most
platforms with most compilers. @command{automake} makes writing complex
@file{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
@file{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 @file{Makefile.in} files such as @command{dist},
@command{distcheck}, @command{clean}, @command{distclean},
@command{maintainer-clean} and @command{tags}, and there are many more more
available. @inforef{Top, GNU automake, automake}, for more information.

Because @code{AM_PATH_GIMPPRINT} calls @code{AC_SUBST} to substitute
@env{GIMPPRINT_CFLAGS}, @env{GIMPPRINT_LIBS} and @env{GIMPPRINT_CONFIG},
@command{automake} will automatically set these variables in the
@file{Makefile.in} files it generates, requiring no additional effort on
your part!

As in previous examples, we will make a program @command{prog} from a file @file{prog.c}. This is how one might build write a @file{Makefile.am} to do this:

@example
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
@end example

That's all there is to it! Please note that this example also requires the
macro @code{AC_PROG_MAKE_SET} to be used in @file{configure.in} and the use of
@code{AC_SUBST} to substitute @env{CFLAGS} and @env{INCLUDES} where
@code{@@CFLAGS@@} and @code{@@INCLUDES@@} are found in the file, respectively.