<chapter>
  <title>Using libgutenprint</title>
  <para>
    This chapter describes how to write programs that use
    libgutenprint.
  </para>
  <sect1>
    <title>Code prerequisites</title>
    <para>
      To use libgutenprint with a program, several steps must be taken:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  Include the master libgutenprint header:
          <informalexample>
            <programlisting>&lt;gimp-print/gimp-print.h&gt;</programlisting>
          </informalexample>
	</para>
      </listitem>
      <listitem>
	<para>
	  Call <function>stp_init</function>.
	</para>
      </listitem>
      <listitem>
	<para>
	  Link with the libgutenprint library.
	</para>
      </listitem>
    </itemizedlist>
    <para>
      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.
    </para>
    <informalexample>
      <programlisting>#include &lt;gimp-print/gimp-print.h&gt;
int
main (int argc, char *argv[])
{
  stp_init();
  return 0;
}
      </programlisting>
    </informalexample>
  </sect1>
  <sect1>
    <title>Linking with libgutenprint</title>
    <para>
      To link a program with libgutenprint, the option
      <option>-lgutenprint</option> needs to be passed to the compiler
      when linking. For example, to compile and link
      <filename>stpimage.c</filename> the following commands would be
      used:
    </para>
    <screen><prompt>$</prompt> <userinput>gcc -c stpimage.c</userinput>
<prompt>$</prompt> <userinput>gcc -o stpimage -lgutenprint stpimage.o</userinput></screen>
    <para>
      The compiler and linker flags needed may vary depending on the
      options Gutenprint was configured with when it was built. The
      <command>pkg-config</command> script will give the correct
      parameters for the local installation.
    </para>
  </sect1>
  <sect1>
    <title>Integrating libgutenprint</title>
    <para>
      This section describes how to integrate the compiling and
      linking of programs using libgutenprint with build
      scripts. Commonly used systems include <command>make</command>,
      but often <filename>Makefile</filename> files are generated by
      using tools such as <command>autoconf</command> and
      <command>automake</command>.
    </para>
    <sect2>
      <title><command>pkg-config</command></title>
      <para>
	Depending on the nature of the computer system Gutenprint was
	installed on, as well as the options passed to
	<command>configure</command> when configuring the package when
	it was built, the <varname>CFLAGS</varname> and
	<varname>LIBS</varname> 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
	<command>pkg-config</command> datafile was created when
	Gutenprint was built.  <command>pkg-config</command> will
	output the correct parameters for the setup on your system.
	See the
	<citerefentry><refentrytitle>pkg-config(1)</refentrytitle>
	</citerefentry> manual page for a compete synopsis.
      </para>
      <para>
	The correct <varname>CFLAGS</varname> to use can be obtained
	with the <option>--cflags</option> option:
      </para>
      <screen><prompt>$</prompt> <userinput>pkg-config --cflags gutenprint</userinput>
-I/usr/local/include</screen>
      <para>
	The correct <varname>LIBS</varname> to use can the obtained
	with the <option>--libs</option> option:
      </para>
      <screen><prompt>$</prompt> <userinput>pkg-config --libs gutenprint</userinput>
-L/usr/local/lib -lgutenprint -lm -ldl</screen>
      <para>
        Lastly, the installed version of Gutenprint can be obtained with the
	<varname>--version</varname> option:
      </para>
      <screen><prompt>$</prompt> <userinput>pkg-config --modversion gutenprint</userinput>
4.3.23</screen>
      <para>
	The command can be used from the shell by enclosing it in
	backquotes &lsquo;`&rsquo;:
      </para>
      <screen><prompt>$</prompt> <userinput>gcc `pkg-config --cflags gutenprint` -c stpimage.c</userinput>
<prompt>$</prompt> <userinput>gcc `pkg-config --libs gutenprint` -o
  stpimage stpimage.o</userinput></screen>
      <para>
	However, this is not the way it it typically used. Normally
	it is used in a <filename>Makefile</filename> or by an m4
	macro in a <command>configure</command> script.
      </para>
    </sect2>
    <sect2>
      <title><command>make</command></title>
      <para>
	If you use <command>make</command> with your own
	<filename>Makefile</filename> 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
	<command>make</command>:
      </para>
      <programlisting>GUTENPRINT_VERSION = $(shell pkg-config --version gutenprint)
GUTENPRINT_CFLAGS = $(shell pkg-config --cflags gutenprint)
GUTENPRINT_LIBS = $(shell pkg-config --libs gutenprint)</programlisting>
      <para>
	How you choose to use these variables is entirely up to
	you. See the GNU <command>make</command> manual for more
	information.
      </para>
    </sect2>
    <sect2>
      <title><command>autoconf</command></title>
      <para>
	The <command>autoconf</command> program produces a Bourne
	shell script called <filename>configure</filename> from a
	template file called <filename>configure.ac</filename>.
	<filename>configure.ac</filename> contains both Bourne shell
	script, and m4 macros.  <command>autoconf</command> expands
	the m4 macros into &lsquo;real&rsquo; shell script.  The
	resulting <command>configure</command> script performs various
	checks for installed programs, compiler characteristics and
	other system information such as available headers and
	libraries.  See the GNU <command>autoconf</command> manual for
	more information.
      </para>
      <para>
	<command>pkg-config</command> provides an m4 macro,
	<function>PKG_CHECK_MODULES</function>, suitable for use in a
	<filename>configure.ac</filename> script.  It defines the
	environment variables required for building libgutenprint-based
	programs.  For example, to set GUTENPRINT_CFLAGS and
	GUTENPRINT_LIBS:
      </para>
      <informalexample>
        <programlisting>PKG_CHECK_MODULES(GUTENPRINT, gutenprint)</programlisting>
      </informalexample>
    </sect2>
    <sect2>
      <title><command>automake</command></title>
      <para>
	The <command>automake</command> program can be used to
	generate <filename>Makefile.in</filename> files suitable for
	use with a <filename>configure</filename> script generated by
	<command>autoconf</command>.  As <command>automake</command>
	<emphasis>requires</emphasis> <command>autoconf</command>,
	this section will assume the use of a
	<filename>configure.ac</filename> script which uses the
	<function>PKG_CHECK_MODULES</function> macro described above
	(there is little point in <emphasis>not</emphasis> using it!).
      </para>
      <para>
        It is highly recommended that you use GNU
	<command>autoconf</command> and
	<command>automake</command>. They will allow you to make your
	software build on most platforms with most compilers.
	<command>automake</command> makes writing complex
	<filename>Makefile</filename>'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
	<filename>Makefile</filename>'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 <filename>Makefile.in</filename> files such as
	<option>dist</option>, <option>distcheck</option>,
	<option>clean</option>, <option>distclean</option>,
	<option>maintainer-clean</option> and <option>tags</option>,
	and there are many more more available.  See the GNU
	<command>automake</command> manual for more information.
      </para>
      <para>
	Because <function>PKG_CHECK_MODULES</function> calls
	<function>AC_SUBST</function> to substitute
	<varname>GUTENPRINT_CFLAGS</varname> and
	<varname>GUTENPRINT_LIBS</varname>, <command>automake</command>
	will automatically set these variables in the
	<filename>Makefile.in</filename> files it generates, requiring
	no additional effort on your part!
      </para>
      <para>
	As in previous examples, we will make a program
	<command>stpimage</command> from
	<filename>stpimage.c</filename>.  This is how one might build
	write a <filename>Makefile.am</filename> to do this:
      </para>
      <informalexample>
        <programlisting>@SET_MAKE@

AM_CFLAGS = $(GUTENPRINT_CFLAGS)

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

MAINTAINERCLEANFILES = Makefile.in</programlisting>
      </informalexample>
      <para>
        That's all there is to it!  Please note that this example also
	requires the macro <function>AC_PROG_MAKE_SET</function> to be
	used in <filename>configure.ac</filename>.
      </para>
    </sect2>
  </sect1>
</chapter>
