1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<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><gimp-print/gimp-print.h></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 <gimp-print/gimp-print.h>
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 ‘`’:
</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 ‘real’ 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>
|
