2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5 <refentry id="glib-building">
7 <refentrytitle>Compiling the GLib package</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>GLib Library</refmiscinfo>
13 <refname>Compiling the GLib Package</refname>
14 <refpurpose>How to compile GLib itself</refpurpose>
17 <refsect1 id="building">
18 <title>Building the Library on UNIX</title>
20 On UNIX, GLib uses the standard GNU build system,
21 using <application>autoconf</application> for package
22 configuration and resolving portability issues,
23 <application>automake</application> for building makefiles
24 that comply with the GNU Coding Standards, and
25 <application>libtool</application> for building shared
26 libraries on multiple platforms. The normal sequence for
27 compiling and installing the GLib library is thus:
30 <userinput>./configure</userinput>
31 <userinput>make</userinput>
32 <userinput>make install</userinput>
37 The standard options provided by <application>GNU
38 autoconf</application> may be passed to the
39 <command>configure</command> script. Please see the
40 <application>autoconf</application> documentation or run
41 <command>./configure --help</command> for information about
45 The GTK+ documentation contains
46 <ulink url="../gtk/gtk-building.html">further details</ulink>
47 about the build process and ways to influence it.
50 <refsect1 id="dependencies">
51 <title>Dependencies</title>
53 Before you can compile the GLib library, you need to have
54 various other tools and libraries installed on your
55 system. The two tools needed during the build process (as
56 differentiated from the tools used in when creating GLib
57 mentioned above such as <application>autoconf</application>)
58 are <command>pkg-config</command> and GNU make.
63 <ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
64 is a tool for tracking the compilation flags needed for
65 libraries that are used by the GLib library. (For each
66 library, a small <literal>.pc</literal> text file is
67 installed in a standard location that contains the compilation
68 flags needed for that library along with version number
69 information.) The version of <command>pkg-config</command>
70 needed to build GLib is mirrored in the
71 <filename>dependencies</filename> directory
72 on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP
78 The GTK+ makefiles will mostly work with different versions
79 of <command>make</command>, however, there tends to be
80 a few incompatibilities, so the GTK+ team recommends
81 installing <ulink url="http://www.gnu.org/software/make">GNU
82 make</ulink> if you don't already have it on your system
83 and using it. (It may be called <command>gmake</command>
84 rather than <command>make</command>.)
89 GLib depends on a number of other libraries.
94 The <ulink url="http://www.gnu.org/software/libiconv/">GNU
95 libiconv library</ulink> is needed to build GLib if your
96 system doesn't have the <function>iconv()</function>
97 function for doing conversion between character
98 encodings. Most modern systems should have
99 <function>iconv()</function>, however many older systems lack
100 an <function>iconv()</function> implementation. On such systems,
101 you must install the libiconv library. This can be found at:
102 <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
105 If your system has an <function>iconv()</function> implementation but
106 you want to use libiconv instead, you can pass the
107 --with-libiconv option to configure. This forces
111 Note that if you have libiconv installed in your default include
112 search path (for instance, in <filename>/usr/local/</filename>), but
113 don't enable it, you will get an error while compiling GLib because
114 the <filename>iconv.h</filename> that libiconv installs hides the
118 If you are using the native iconv implementation on Solaris
119 instead of libiconv, you'll need to make sure that you have
120 the converters between locale encodings and UTF-8 installed.
121 At a minimum you'll need the SUNWuiu8 package. You probably
122 should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
126 The native iconv on Compaq Tru64 doesn't contain support for
127 UTF-8, so you'll need to use GNU libiconv instead. (When
128 using GNU libiconv for GLib, you'll need to use GNU libiconv
129 for GNU gettext as well.) This probably applies to related
130 operating systems as well.
135 The libintl library from the <ulink
136 url="http://www.gnu.org/software/gettext">GNU gettext
137 package</ulink> is needed if your system doesn't have the
138 <function>gettext()</function> functionality for handling
139 message translation databases.
144 A thread implementation is needed. The thread support in GLib
145 can be based upon POSIX threads or win32 threads.
150 GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
151 for regular expression matching. The default is to use the internal
152 version of PCRE that is patched to use GLib for memory management
153 and Unicode handling. If you prefer to use the system-supplied PCRE
154 library you can pass the <option>--with-pcre=system</option> option
155 to, but it is not recommended.
160 The optional extended attribute support in GIO requires the
161 getxattr() family of functions that may be provided by glibc or
162 by the standalone libattr library. To build GLib without extended
163 attribute support, use the <option>--disable-xattr</option>
169 The optional SELinux support in GIO requires libselinux.
170 To build GLib without SELinux support, use the
171 <option>--disable-selinux</option> option.
176 The optional support for DTrace requires the
177 <filename>sys/sdt.h</filename> header, which is provided
178 by SystemTap on Linux. To build GLib without DTrace, use
179 the <option>--disable-dtrace</option> configure option.
184 The optional support for
185 <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
186 can be disabled with the <option>--disable-systemtap</option>
193 <refsect1 id="extra-configuration-options">
194 <title>Extra Configuration Options</title>
197 In addition to the normal options, the
198 <command>configure</command> script in the GLib
199 library supports these additional arguments:
203 <title><systemitem>--enable-debug</systemitem></title>
206 Turns on various amounts of debugging support. Setting this to 'no'
207 disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
208 all cast checks between different object types. Setting it to 'minimum' disables only cast checks. Setting it to 'yes' enables
209 <link linkend="G-DEBUG:CAPS">runtime debugging</link>.
210 The default is 'minimum'.
211 Note that 'no' is fast, but dangerous as it tends to destabilize
212 even mostly bug-free software by changing the effect of many bugs
213 from simple warnings into fatal crashes. Thus
214 <option>--enable-debug=no</option> should <emphasis>not</emphasis>
215 be used for stable releases of GLib.
220 <title><systemitem>--disable-gc-friendly</systemitem> and
221 <systemitem>--enable-gc-friendly</systemitem></title>
224 By default, and with <systemitem>--disable-gc-friendly</systemitem>
225 as well, Glib does not clear the memory for certain objects before
226 they are freed. For example, Glib may decide to recycle GList nodes
227 by putting them in a free list. However, memory profiling and debugging
228 tools like <ulink url="http://www.valgrind.org">Valgrind</ulink> work
229 better if an application does not keep dangling pointers to freed
230 memory (even though these pointers are no longer dereferenced), or
231 invalid pointers inside uninitialized memory.
232 The <systemitem>--enable-gc-friendly</systemitem> option makes Glib
233 clear memory in these situations:
239 When shrinking a GArray, Glib will clear the memory no longer
240 available in the array: shrink an array from 10 bytes to 7, and
241 the last 3 bytes will be cleared. This includes removals of single
242 and multiple elements.
247 When growing a GArray, Glib will clear the new chunk of memory.
248 Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will
254 The above applies to GPtrArray as well.
259 When freeing a node from a GHashTable, Glib will first clear
260 the node, which used to have pointers to the key and the value
266 When destroying or removing a GTree node, Glib will clear the node,
267 which used to have pointers to the node's value, and the left and
274 Since clearing the memory has a cost,
275 <systemitem>--disable-gc-friendly</systemitem> is the default.
280 <title><systemitem>--disable-mem-pools</systemitem> and
281 <systemitem>--enable-mem-pools</systemitem></title>
284 Many small chunks of memory are often allocated via collective pools
285 in GLib and are cached after release to speed up reallocations.
286 For sparse memory systems this behaviour is often inferior, so
287 memory pools can be disabled to avoid excessive caching and force
288 atomic maintenance of chunks through the <function>g_malloc()</function>
289 and <function>g_free()</function> functions. Code currently affected by
294 <structname>GMemChunk</structname>s become basically non-effective
299 <structname>GSignal</structname> disables all caching
300 (potentially very slow)
305 <structname>GType</structname> doesn't honour the
306 <structname>GTypeInfo</structname>
307 <structfield>n_preallocs</structfield> field anymore
312 the <structname>GBSearchArray</structname> flag
313 <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
321 <title><systemitem>--with-threads</systemitem></title>
324 Specify a thread implementation to use. Available options are
325 'posix' or 'win32'. Normally, <command>configure</command>
326 should be able to work out the system threads API on its own.
331 <title><systemitem>--disable-regex</systemitem> and
332 <systemitem>--enable-regex</systemitem></title>
335 Do not compile GLib with regular expression support.
336 GLib will be smaller because it will not need the
337 PCRE library. This is however not recommended, as
338 programs may need GRegex.
343 <title><systemitem>--with-pcre</systemitem></title>
346 Specify whether to use the internal or the system-supplied
351 'internal' means that GRegex will be compiled to use
352 the internal PCRE library.
357 'system' means that GRegex will be compiled to use
358 the system-supplied PCRE library.
362 Using the internal PCRE is the preferred solution:
366 System-supplied PCRE has a separated copy of the big tables
367 used for Unicode handling.
372 Some systems have PCRE libraries compiled without some needed
373 features, such as UTF-8 and Unicode support.
378 PCRE uses some global variables for memory management and
379 other features. In the rare case of a program using both
380 GRegex and PCRE (maybe indirectly through a library),
381 this variables could lead to problems when they are modified.
389 <title><systemitem>--disable-included-printf</systemitem> and
390 <systemitem>--enable-included-printf</systemitem></title>
393 By default the <command>configure</command> script will try
394 to auto-detect whether the C library provides a suitable set
395 of printf() functions. In detail, <command>configure</command>
396 checks that the semantics of snprintf() are as specified by C99
397 and that positional parameters as specified in the Single Unix
398 Specification are supported. If this not the case, GLib will
399 include an implementation of the printf() family.
402 These options can be used to explicitly control whether
403 an implementation of the printf() family should be included or not.
408 <title><systemitem>--disable-Bsymbolic</systemitem> and
409 <systemitem>--enable-Bsymbolic</systemitem></title>
412 By default, GLib uses the -Bsymbolic-functions linker
413 flag to avoid intra-library PLT jumps. A side-effect
414 of this is that it is no longer possible to override
415 internal uses of GLib functions with
416 <envar>LD_PRELOAD</envar>. Therefore, it may make
417 sense to turn this feature off in some situations.
418 The <option>--disable-Bsymbolic</option> option allows
424 <title><systemitem>--disable-gtk-doc</systemitem> and
425 <systemitem>--enable-gtk-doc</systemitem></title>
428 By default the <command>configure</command> script will try
429 to auto-detect whether the
430 <application>gtk-doc</application> package is installed.
431 If it is, then it will use it to extract and build the
432 documentation for the GLib library. These options
433 can be used to explicitly control whether
434 <application>gtk-doc</application> should be
435 used or not. If it is not used, the distributed,
436 pre-generated HTML files will be installed instead of
437 building them on your machine.
442 <title><systemitem>--disable-man</systemitem> and
443 <systemitem>--enable-man</systemitem></title>
446 By default the <command>configure</command> script will try
447 to auto-detect whether <application>xsltproc</application>
448 and the necessary Docbook stylesheets are installed.
449 If they are, then it will use them to rebuild the included
450 man pages from the XML sources. These options can be used
451 to explicitly control whether man pages should be rebuilt
452 used or not. The distribution includes pre-generated man
458 <title><systemitem>--disable-xattr</systemitem> and
459 <systemitem>--enable-xattr</systemitem></title>
462 By default the <command>configure</command> script will try
463 to auto-detect whether the getxattr() family of functions
464 is available. If it is, then extended attribute support
465 will be included in GIO. These options can be used to
466 explicitly control whether extended attribute support
467 should be included or not. getxattr() and friends can
468 be provided by glibc or by the standalone libattr library.
473 <title><systemitem>--disable-selinux</systemitem> and
474 <systemitem>--enable-selinux</systemitem></title>
477 By default the <command>configure</command> script will
478 auto-detect if libselinux is available and include
479 SELinux support in GIO if it is. These options can be
480 used to explicitly control whether SELinux support should
486 <title><systemitem>--disable-dtrace</systemitem> and
487 <systemitem>--enable-dtrace</systemitem></title>
490 By default the <command>configure</command> script will
491 detect if DTrace support is available, and use it.
496 <title><systemitem>--disable-systemtap</systemitem> and
497 <systemitem>--enable-systemtap</systemitem></title>
500 This option requires DTrace support. If it is available, then
501 the <command>configure</command> script will also check for
502 the presence of SystemTap.
507 <title><systemitem>--enable-gcov</systemitem> and
508 <systemitem>--disable-gcov</systemitem></title>
511 Enable the generation of coverage reports for the GLib tests.
512 This requires the lcov frontend to gcov from the
513 <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
514 To generate a coverage report, use the lcov make target. The
515 report is placed in the <filename>glib-lcov</filename> directory.
520 <title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title>
523 Allows specifying a relative path to where to install the runtime
524 libraries (meaning library files used for running, not developing,
525 GLib applications). This can be used in operating system setups where
526 programs using GLib needs to run before e.g. <filename>/usr</filename>
528 For example, if LIBDIR is <filename>/usr/lib</filename> and
529 <filename>../../lib</filename> is passed to
530 <systemitem>--with-runtime-libdir</systemitem> then the
531 runtime libraries are installed into <filename>/lib</filename> rather
532 than <filename>/usr/lib</filename>.
537 <title><systemitem>--with-python</systemitem></title>
540 Allows specifying the Python interpreter to use, either as an absolute path,
541 or as a program name. GLib can be built with Python 2 (at least version 2.5)