1 <refentry id="gtk-building" revision="6 Sept 2001">
3 <refentrytitle>Compiling the GTK+ libraries</refentrytitle>
4 <manvolnum>3</manvolnum>
5 <refmiscinfo>GTK Library</refmiscinfo>
9 <refname>Compiling the GTK+ Libraries</refname>
11 How to compile GTK+ itself
14 <refsect1 id="overview">
15 <title>Building GTK+ on UNIX-like systems</title>
17 This chapter covers building and installing GTK+ on UNIX and
18 UNIX-like systems such as Linux. Compiling GTK+ on Microsoft
19 Windows is different in detail and somewhat more difficult to
20 get going since the necessary tools aren't included with
24 Before we get into the details of how to compile GTK+, we should
25 mention that in many cases, binary packages of GTK+ prebuilt for
26 your operating system will be available, either from your
27 operating system vendor or from independent sources. If such a
28 set of packages is available, installing it will get you
29 programming wih GTK+ much faster than building it yourself. In
30 fact, you may well already have GTK+ installed on your system
34 On UNIX-like systems GTK+ uses the standard GNU build system,
35 using <application>autoconf</application> for package
36 configuration and resolving portability issues,
37 <application>automake</application> for building makefiles that
38 comply with the GNU Coding Standards, and
39 <application>libtool</application> for building shared libraries
40 on multiple platforms.
43 If you are building GTK+ from the distributed source packages,
44 then won't need these tools installed; the necessary pieces
45 of the tools are already included in the source packages. But
46 it's useful to know a bit about how packages that use these
47 tools work. A source package is distributed as a
48 <literal>tar.gz</literal> file which you unpack into a
49 directory full of the source files as follows:
52 tar xvfz gtk+-2.0.0.tar.gz
55 In the toplevel of the directory that is created, there will be
56 a shell script called <filename>configure</filename> which
57 you then run to take the template makefiles called
58 <filename>Makefile.in</filename> in the package and create
59 makefiles customized for your operating system. The <filename>configure</filename>
60 script can be passed various command line arguments to determine how
61 the package is built and installed. The most commonly useful
62 argument is the <systemitem>--prefix</systemitem> argument which
63 determines where the package is installed. To install a package
64 in <filename>/opt/gtk</filename> you would run configure as:
67 ./configure --prefix=/opt/gtk
70 A full list of options can be found by running
71 <filename>configure</filename> with the
72 <systemitem>--help</systemitem> argument. In general, the defaults are
73 right and should be trusted. After you've run
74 <filename>configure</filename>, you then run the
75 <command>make</command> command to build the package and install
83 If you don't have permission to write to the directory you are
84 installing in, you may have to change to root temporarily before
85 running <literal>make install</literal>.
88 Several environment variables are useful to pass to set before
89 running configure. <envar>CPPFLAGS</envar> contains options to
90 pass to the C compiler, and is used to tell the compiler where
91 to look for include files. The <envar>LDFLAGS</envar> variable
92 is used in a similar fashion for the linker. Finally the
93 <envar>PKG_CONFIG_PATH</envar> environment variable contains
94 a search path that <command>pkg-config</command> (see below)
95 uses when looking for for file describing how to compile
96 programs using different libraries. If you were installing GTK+
97 and it's dependencies into /opt/gtk, you might want to set
101 CPPFLAGS="-I /opt/gtk/include"
102 LDFLAGS="-L/opt/gtk/lib"
103 PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
104 export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
107 You may also need to set the <envar>LD_LIBRARY_PATH</envar>
108 environment variable so the systems dynamic linker can find
109 the newly installed libraries, and the <envar>PATH</envar>
110 environment program so that utility binaries installed by
111 the various libraries will be found.
114 LD_LIBRARY_PATH="/opt/gtk/lib"
115 PATH="/opt/gtk/bin:$PATH"
116 export LD_LIBRARY_PATH PATH
119 <refsect1 id="dependencies">
120 <title>Dependencies</title>
122 Before you can compile the GTK+ widget toolkit, you need to have
123 various other tools and libraries installed on your
124 system. The two tools needed during the build process (as
125 differentiated from the tools used in when creating GTK+
126 mentioned above such as <application>autoconf</application>)
127 are <command>pkg-config</command> and GNU make.
133 url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
134 is a tool for tracking the compilation flags needed for
135 libraries that is used by the GTK+ libraries. (For each
136 library, a small ".pc" text file is installed in a standard
137 location that contains the compilation flags needed for that
138 library along with version number information.) The version
139 of <command>pkg-config</command> needed to build GTK+ is
140 mirrored in the <filename>dependencies</filename> directory
141 on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+ FTP
147 The GTK+ makefiles will mostly work with different versions
148 of <command>make</command>, however, there tends to be
149 a few incompatibilities, so the GTK+ team recommends
150 installing <ulink url="http://www.gnu.org/software/make">GNU
151 make</ulink> if you don't already have it on your system
152 and using it. (It may be called <command>gmake</command>
153 rather than <command>make</command>)
158 Three of the libraries that GTK+ depends on are maintained by
159 by the GTK+ team: GLib, Pango, and ATK. Other libraries are
160 maintained separately.
165 The GLib library provides core non-graphical functionality
166 such as high level data types, unicode manipulation, and
167 a object and type system to C programs. It is available
168 from the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+
174 Pango is a library for internationalized text handling. It
175 is available from the <ulink
176 url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+ FTP site.</ulink>
181 ATK is the Accessibility Toolkit. It provides a set of generic
182 interfaces allowing accessibility technologies such as
183 screen readers to interact with a graphical user interface.
184 It is available from the <ulink
185 url="ftp://ftp.gtk.org/pub/gtk/v2.0/">GTK+ FTP site.</ulink>
190 The <ulink url="http://www.gnu.org/software/libiconv/">GNU
191 libiconv library</ulink> is needed to build GLib if your
192 system doesn't have the <function>iconv()</function>
193 function for doing conversion between character
194 encodings. Most modern systems should have
195 <function>iconv()</function>.
200 The libintl library from the <ulink
201 url="http://www.gtk.org/software/gettext">GNU gettext
202 package</ulink> is needed if your system doesn't have the
203 <function>gettext()</function> functionality for handling
204 message translation databases.
210 url="ftp://ftp.uu.net/graphics/jpeg/">JPEG</ulink>,
211 <ulink url="http://www.libpng.org">PNG</ulink>, and
212 <ulink url="http://www.libtiff.org">TIFF</ulink> image loading libraries are needed to
213 compile GTK+. You probably already have these libraries
214 installed, but if not, the versions you need are available in
215 the <filename>dependencies</filename> directory on the the
216 <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.0/dependencies/">GTK+
217 FTP site.</ulink>. (Before installing these libraries
218 from source, you should check if your operating system
219 vendor has prebuilt packages of these libraries that you
220 don't have installed.)
225 While not required for running GTK+ on X, you may want install the
226 <ulink url="http://www.freetype.org">FreeType
227 library</ulink> so that the PangoFT2 backend for Pango will
228 be built. This backend is used by the linux-fb backend for
229 GTK+ and applications that want to render independently
230 of the X display. You'll need at least version 2.0.1.
235 The libraries from the X window system are needed to build
236 Pango and GTK+. You should already have these installed on
237 your system, but it's possible that you'll need to install
238 the development environment for these libraries that your
239 operating system vendor provides. If you have a recent
240 version of the XFree86 system, such as 4.2.0, then Pango
241 and GTK+ will take advantage of the Xft and Xrender
242 libraries to provide anti-aliased and scaleable fonts in
243 a much more sophisticated fashion then the support for
249 <refsect1 id="building">
250 <title>Building and testing GTK+</title>
252 First make sure that you have the necessary external
253 dependencies installed: <command>pkg-config</command>, GNU make,
254 the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
255 libiconv and libintl. To get detailed information about building
256 ithese packages, see the documentation provided with the
258 On a Linux system, it's quite likely you'll have all of these
259 installed already except for <command>pkg-config</command>.
262 Then build and install the GTK+ libraries in the order:
263 GLib, Pango, ATK, then GTK+. For each library, follow the
264 steps of <literal>configure</literal>, <literal>make</literal>,
265 <literal>make install</literal> mentioned above. If you're
266 lucky, this will all go smoothly, and you'll be ready to
267 <link linkend="gtk-compiling">start compiling your own GTK+
268 applications</link>. You can test your GTK+ installation
269 by running the <command>gtk-demo</command> program that
270 GTK+ installs. If you have the Xft library, you can turn on
271 anti-aliased fonts by setting the <envar>GDK_USE_XFT</envar>
272 environment variable.
275 GDK_USE_XFT=1 gtk-demo
278 If one of the <filename>configure</filename> scripts fails or running
279 <command>make</command> fails, look closely at the at the error
280 messages printed; these will often provide useful information
281 as to what went wrong. When <filename>configure</filename>
282 fails, extra information, such as errors that a test compilation
283 ran into, is found in the file <filename>config.log</filename>.
284 Looking at the last couple of hundred lines in this file will
285 frequently make clear what went wrong. If all else fails, you
286 can ask for help on the gtk-list mailing list.
287 See <xref linkend="gtk-resources"> for more information.
290 <refsect1 id="extra-configuration-options">
291 <title>Extra Configuration Options</title>
294 In addition to the normal options, the
295 <command>configure</command> script for the GTK+ library
296 supports a number of additional arguments. (Command line
297 arguments for the other GTK+ libraries are described in
298 the documentation distributed with the those libraries.)
301 <command>configure</command>
304 <arg>--disable-modules</arg>
305 <arg>--enable-modules</arg>
308 <arg>--with-included-loaders==LOADER1,LOADER2,...</arg>
311 <arg>--enable-debug=[no|minimum|yes]</arg>
314 <arg>--disable-shm</arg>
315 <arg>--enable-shm</arg>
318 <arg>--disable-xim</arg>
319 <arg>--enable-xim</arg>
322 <arg>--disable-xim-inst</arg>
323 <arg>--enable-xim-inst</arg>
326 <arg>--disable-xkb</arg>
327 <arg>--enable-xkb</arg>
330 <arg>--disable-gtk-doc</arg>
331 <arg>--enable-gtk-doc</arg>
334 <arg>--with-xinput=[no|gxi|xfree]</arg>
337 <arg>--with-gdktarget=[x11|linux-fb|win32]</arg>
340 <arg>--disable-shadowfb</arg>
341 <arg>--enable-shadowfb</arg>
347 <title><systemitem>--disable-modules</systemitem> and
348 <systemitem>--enable-modules</systemitem></title>
351 Normally GTK+ will try to build the GdkPixbuf image file
352 format loaders as little shared libraries that are loaded on
353 demand. The <systemitem>--disable-modules</systemitem>
354 argument indicates that they should all be built statically
355 into the GTK+ library instead. This is useful for
356 people who need to produce statically-linked binaries. If
357 neither <systemitem>--disable-modules</systemitem> nor
358 <systemitem>--enable-modules</systemitem> is specified, then
359 the <command>configure</command> script will try to
360 auto-detect whether shared modules work on your system.
365 <title><systemitem>--with-included-loaders</systemitem></title>
368 This option allows you to specify which image loaders you
369 want to include; for example, you might include only the PNG
370 loader to create a smaller GdkPixbuf binary.
375 <title><systemitem>--enable-debug</systemitem></title>
378 Turns on various amounts of debugging support. Setting this to 'no'
379 disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
380 all cast checks between different object types. Setting it to 'minimum'
381 disables only cast checks. Setting it to 'yes' enables
382 <link linkend="GTK-Debug-Options">runtime debugging</link>.
383 The default is 'minimum'.
384 Note that 'no' is fast, but dangerous as it tends to destabilize
385 even mostly bug-free software by changing the effect of many bugs
386 from simple warnings into fatal crashes. Thus
387 <option>--enable-debug=no</option> should <emphasis>not</emphasis>
388 be used for stable releases of gtk+.
393 <title><systemitem>--enable-explicit-deps</systemitem> and
394 <systemitem>--disable-explicit-deps</systemitem></title>
396 If <systemitem>--enable-explicit-deps</systemitem> is
397 specified then GTK+ will write the full set of libraries
398 that GTK+ depends upon into its .pc files to be used when
399 programs depending on GTK+ are linked. Otherwise, GTK+
400 only will include the GTK+ libraries themselves, and
401 will depend on system library dependency facilities to
402 bring in the other libraries.
403 By default GTK+ will disable explicit dependencies unless
404 it detects that they are needed on the system. (If you
405 specify <systemitem>--enable-static</systemitem> to force
406 building of static libraries, then explicit dependencies
407 will be written since library dependencies don't work
408 for static libraries.) Specifying
409 <systemitem>--enable-explicit-deps</systemitem> or
410 <systemitem>--enable-static</systemitem> can cause
412 problems when libraries that GTK+ depends upon change
413 their versions, and should be avoided if possible.
418 <title><systemitem>--disable-shm</systemitem> and
419 <systemitem>--enable-shm</systemitem></title>
422 These options can be used to control whether GTK+ will use shared
423 memory to communicate with the X server when possible.
429 <title><systemitem>--disable-xim</systemitem> and
430 <systemitem>--enable-xim</systemitem></title>
433 These options can be used to control whether GTK+ will
434 be compiled with support for XIM.
440 <title><systemitem>--disable-xim-inst</systemitem> and
441 <systemitem>--enable-xim-inst</systemitem></title>
444 These options determine whether GTK+ will use the
445 XIM instantiate callback.
446 The default is yes, unless the host system is Solaris,
447 where <function>XRegisterIMInstantiateCallback</function>
448 seems to cause a segfault.
453 <title><systemitem>--disable-xkb</systemitem> and
454 <systemitem>--enable-xkb</systemitem></title>
457 By default the <command>configure</command> script will try
458 to auto-detect whether the XKB extension is supported by
459 the X libraries GTK+ is linked with.
460 These options can be used to explicitly control whether
461 GTK+ will support the XKB extension.
466 <title><systemitem>--disable-gtk-doc</systemitem> and
467 <systemitem>--enable-gtk-doc</systemitem></title>
470 The <application>gtk-doc</application> package is
471 used to generate the reference documented included
472 with GTK+. By default support for gtk-doc is disabled
473 because it requires various extra dependencies
474 to be installed. If you have
475 <application>gtk-doc</application> installed and
476 are modifying GTK+, you may want to enable
477 <application>gtk-doc</application> support by passing
478 in <systemitem>--enable-gtk-doc</systemitem>. If not
479 enabled pre-generated HTML files distributed with GTK+
485 <title><systemitem>--with-xinput</systemitem></title>
487 Controls whether GTK+ is built with support for the XInput
488 extension. The XInput extension provides an interface
489 to extended input devices such as graphics tablets.
490 When this support is compiled in, specially written
491 GTK+ programs can get access to subpixel positions,
492 multiple simultaneous input devices, and extra "axes"
493 provided by the device such as pressure and tilt
494 information. This is only known to work well on XFree86
495 systems, though other systems do have this extension.
496 (If <systemitem>--with-xinput=gxi</systemitem>
497 is supplied, support for an obsolete and unsupported
498 way of interacting with XInput is compiled.)
502 <title><systemitem>--with-gdktarget</systemitem></title>
505 Toggles between the supported backends for GDK.
506 The default is x11, unless the platform is Windows, in which
507 case the default is win32.
512 <title><systemitem>--disable-shadowfb</systemitem> and
513 <systemitem>--enable-shadowfb</systemitem></title>
516 Toggles shadow framebuffer support for the linux-fb target,
525 <!-- Local Variables: -->
526 <!-- sgml-parent-document: ("gtk-docs.sgml" "chapter" "refentry") -->