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
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 option:
$pkg-config --cflags gutenprint
-I/usr/local/include
The correct LIBS to use can the obtained
with the 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 automakerequiresautoconf,
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
, ,
, ,
and ,
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.