2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
5 <refentry id="glib-building" revision="16 Jan 2002">
7 <refentrytitle>Compiling the GLib package</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>GLib Library</refmiscinfo>
13 <refname>Compiling the GLib Package</refname>
15 How to compile GLib itself
19 <refsect1 id="building">
20 <title>Building the Library on UNIX</title>
22 On UNIX, GLib uses the standard GNU build system,
23 using <application>autoconf</application> for package
24 configuration and resolving portability issues,
25 <application>automake</application> for building makefiles
26 that comply with the GNU Coding Standards, and
27 <application>libtool</application> for building shared
28 libraries on multiple platforms. The normal sequence for
29 compiling and installing the GLib library is thus:
32 <userinput>./configure</userinput>
33 <userinput>make</userinput>
34 <userinput>make install</userinput>
39 The standard options provided by <application>GNU
40 autoconf</application> may be passed to the
41 <command>configure</command> script. Please see the
42 <application>autoconf</application> documentation or run
43 <command>./configure --help</command> for information about
47 The GTK+ documentation contains
48 <ulink url="../gtk/gtk-building.html">further details</ulink>
49 about the build process and ways to influence it.
52 <refsect1 id="dependencies">
53 <title>Dependencies</title>
55 Before you can compile the GLib library, you need to have
56 various other tools and libraries installed on your
57 system. The two tools needed during the build process (as
58 differentiated from the tools used in when creating GLib
59 mentioned above such as <application>autoconf</application>)
60 are <command>pkg-config</command> and GNU make.
66 url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
67 is a tool for tracking the compilation flags needed for
68 libraries that are used by the GLib library. (For each
69 library, a small <literal>.pc</literal> text file is
70 installed in a standard location that contains the compilation
71 flags needed for that library along with version number
72 information.) The version of <command>pkg-config</command>
73 needed to build GLib is mirrored in the
74 <filename>dependencies</filename> directory
75 on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP
81 The GTK+ makefiles will mostly work with different versions
82 of <command>make</command>, however, there tends to be
83 a few incompatibilities, so the GTK+ team recommends
84 installing <ulink url="http://www.gnu.org/software/make">GNU
85 make</ulink> if you don't already have it on your system
86 and using it. (It may be called <command>gmake</command>
87 rather than <command>make</command>.)
92 GLib depends on a number of other libraries.
97 The <ulink url="http://www.gnu.org/software/libiconv/">GNU
98 libiconv library</ulink> is needed to build GLib if your
99 system doesn't have the <function>iconv()</function>
100 function for doing conversion between character
101 encodings. Most modern systems should have
102 <function>iconv()</function>, however many older systems lack
103 an <function>iconv()</function> implementation. On such systems,
104 you must install the libiconv library. This can be found at:
105 <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
108 If your system has an <function>iconv()</function> implementation but
109 you want to use libiconv instead, you can pass the
110 --with-libiconv option to configure. This forces
114 Note that if you have libiconv installed in your default include
115 search path (for instance, in <filename>/usr/local/</filename>), but
116 don't enable it, you will get an error while compiling GLib because
117 the <filename>iconv.h</filename> that libiconv installs hides the
121 If you are using the native iconv implementation on Solaris
122 instead of libiconv, you'll need to make sure that you have
123 the converters between locale encodings and UTF-8 installed.
124 At a minimum you'll need the SUNWuiu8 package. You probably
125 should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
129 The native iconv on Compaq Tru64 doesn't contain support for
130 UTF-8, so you'll need to use GNU libiconv instead. (When
131 using GNU libiconv for GLib, you'll need to use GNU libiconv
132 for GNU gettext as well.) This probably applies to related
133 operating systems as well.
138 The libintl library from the <ulink
139 url="http://www.gnu.org/software/gettext">GNU gettext
140 package</ulink> is needed if your system doesn't have the
141 <function>gettext()</function> functionality for handling
142 message translation databases.
147 A thread implementation is needed, unless you want to compile GLib
148 without thread support, which is not recommended. The thread support
149 in GLib can be based upon several native thread implementations,
150 e.g. POSIX threads, DCE threads or Solaris threads.
155 GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
156 for regular expression matching. The default is to use the internal
157 version of PCRE that is patched to use GLib for memory management
158 and Unicode handling. If you prefer to use the system-supplied PCRE
159 library you can pass the --with-pcre=system option to configure,
160 but it is not recommended.
165 The optional extended attribute support in GIO requires the
166 getxattr() family of functions that may be provided by glibc or
167 by the standalone libattr library. To build GLib without extended
168 attribute support, use the <option>--disable-xattr</option>
174 The optional SELinux support in GIO requires libselinux. To build
175 GLib without SELinux support, use the
176 <option>--disable-selinux</option> configure option.
181 The optional support for DTrace requires the <filename>sys/sdt.h</filename> header,
182 which is provided by SystemTap on Linux. To build GLib without DTrace, use the
183 <option>--disable-dtrace</option> configure option.
188 The optional support for <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> can be disabled with the
189 <option>--disable-systemtap</option> configure option.
195 <refsect1 id="extra-configuration-options">
196 <title>Extra Configuration Options</title>
199 In addition to the normal options, the
200 <command>configure</command> script in the GLib
201 library supports these additional arguments:
204 <command>configure</command>
206 <arg>--enable-debug=[no|minimum|yes]</arg>
209 <arg>--disable-gc-friendly</arg>
210 <arg>--enable-gc-friendly</arg>
213 <arg>--disable-mem-pools</arg>
214 <arg>--enable-mem-pools</arg>
217 <arg>--disable-threads</arg>
218 <arg>--enable-threads</arg>
221 <arg>--with-threads=[none|posix|dce|win32]</arg>
224 <arg>--disable-regex</arg>
225 <arg>--enable-regex</arg>
228 <arg>--with-pcre=[internal|system]</arg>
231 <arg>--disable-included-printf</arg>
232 <arg>--enable-included-printf</arg>
235 <arg>--disable-Bsymbolic</arg>
236 <arg>--enable-Bsymbolic</arg>
239 <arg>--disable-gtk-doc</arg>
240 <arg>--enable-gtk-doc</arg>
243 <arg>--disable-man</arg>
244 <arg>--enable-man</arg>
247 <arg>--disable-xattr</arg>
248 <arg>--enable-xattr</arg>
251 <arg>--disable-selinux</arg>
252 <arg>--enable-selinux</arg>
255 <arg>--disable-dtrace</arg>
256 <arg>--enable-dtrace</arg>
259 <arg>--disable-systemtap</arg>
260 <arg>--enable-systemtap</arg>
263 <arg>--enable-gcov</arg>
264 <arg>--disable-gcov</arg>
267 <arg>--with-runtime-libdir=RELPATH</arg>
273 <title><systemitem>--enable-debug</systemitem></title>
276 Turns on various amounts of debugging support. Setting this to 'no'
277 disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
278 all cast checks between different object types. Setting it to 'minimum' disables only cast checks. Setting it to 'yes' enables
279 <link linkend="G-DEBUG:CAPS">runtime debugging</link>.
280 The default is 'minimum'.
281 Note that 'no' is fast, but dangerous as it tends to destabilize
282 even mostly bug-free software by changing the effect of many bugs
283 from simple warnings into fatal crashes. Thus
284 <option>--enable-debug=no</option> should <emphasis>not</emphasis>
285 be used for stable releases of GLib.
290 <title><systemitem>--disable-gc-friendly</systemitem> and
291 <systemitem>--enable-gc-friendly</systemitem></title>
294 By default, and with <systemitem>--disable-gc-friendly</systemitem>
295 as well, Glib does not clear the memory for certain objects before they
296 are freed. For example, Glib may decide to recycle GList nodes by
297 putting them in a free list. However, memory profiling and debugging tools like <ulink
298 url="http://www.valgrind.org">Valgrind</ulink> work better if an
299 application does not keep dangling pointers to freed memory (even
300 though these pointers are no longer dereferenced), or invalid pointers inside
301 uninitialized memory. The
302 <systemitem>--enable-gc-friendly</systemitem> option makes Glib clear
303 memory in these situations:
310 When shrinking a GArray, Glib will clear the memory no longer
311 available in the array: shrink an array from 10 bytes to 7, and
312 the last 3 bytes will be cleared. This includes removals of single and multiple elements.
321 When growing a GArray, Glib will clear the new chunk of memory.
322 Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will be cleared.
327 The above applies to GPtrArray as well.
332 When freeing a node from a GHashTable, Glib will first clear
333 the node, which used to have pointers to the key and the value
339 When destroying or removing a GTree node, Glib will clear the node,
340 which used to have pointers to the node's value, and the left and right subnodes.
346 Since clearing the memory has a cost,
347 <systemitem>--disable-gc-friendly</systemitem> is the default.
351 <title><systemitem>--disable-mem-pools</systemitem> and
352 <systemitem>--enable-mem-pools</systemitem></title>
355 Many small chunks of memory are often allocated via collective pools
356 in GLib and are cached after release to speed up reallocations.
357 For sparse memory systems this behaviour is often inferior, so
358 memory pools can be disabled to avoid excessive caching and force
359 atomic maintenance of chunks through the <function>g_malloc()</function>
360 and <function>g_free()</function> functions. Code currently affected by
365 <structname>GList</structname>, <structname>GSList</structname>,
366 <structname>GNode</structname>, <structname>GHash</structname>
367 allocations. The functions g_list_push_allocator(),
368 g_list_pop_allocator(), g_slist_push_allocator(),
369 g_slist_pop_allocator(), g_node_push_allocator() and
370 g_node_pop_allocator() are not available
375 <structname>GMemChunk</structname>s become basically non-effective
380 <structname>GSignal</structname> disables all caching (potentially
386 <structname>GType</structname> doesn't honour the
387 <structname>GTypeInfo</structname>
388 <structfield>n_preallocs</structfield> field anymore
393 the <structname>GBSearchArray</structname> flag
394 <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
402 <title><systemitem>--disable-threads</systemitem> and
403 <systemitem>--enable-threads</systemitem></title>
406 Do not compile GLib to be multi thread safe. GLib
407 will be slightly faster then. This is however not
408 recommended, as many programs rely on GLib being
414 <title><systemitem>--with-threads</systemitem></title>
417 Specify a thread implementation to use.
420 'posix' and 'dce' can be used interchangeable
421 to mean the different versions of Posix
422 threads. configure tries to find out, which
427 'none' means that GLib will be thread safe,
428 but does not have a default thread
429 implementation. This has to be supplied to
430 <function>g_thread_init()</function> by the programmer.
438 <title><systemitem>--disable-regex</systemitem> and
439 <systemitem>--enable-regex</systemitem></title>
442 Do not compile GLib with regular expression support.
443 GLib will be smaller because it will not need the
444 PCRE library. This is however not recommended, as
445 programs may need GRegex.
450 <title><systemitem>--with-pcre</systemitem></title>
453 Specify whether to use the internal or the system-supplied
457 'internal' means that GRegex will be compiled to use
458 the internal PCRE library.
462 'system' means that GRegex will be compiled to use
463 the system-supplied PCRE library.
466 Using the internal PCRE is the preferred solution:
470 System-supplied PCRE has a separated copy of the big tables
471 used for Unicode handling.
476 Some systems have PCRE libraries compiled without some needed
477 features, such as UTF-8 and Unicode support.
482 PCRE uses some global variables for memory management and
483 other features. In the rare case of a program using both
484 GRegex and PCRE (maybe indirectly through a library),
485 this variables could lead to problems when they are modified.
493 <title><systemitem>--disable-included-printf</systemitem> and
494 <systemitem>--enable-included-printf</systemitem></title>
497 By default the <command>configure</command> script will try
498 to auto-detect whether the C library provides a suitable set
499 of <function>printf()</function> functions. In detail,
500 <command>configure</command> checks that the semantics of
501 <function>snprintf()</function> are as specified by C99 and
502 that positional parameters as specified in the Single Unix
503 Specification are supported. If this not the case, GLib will
504 include an implementation of the <function>printf()</function>
506 These options can be used to explicitly control whether
507 an implementation fo the <function>printf()</function> family
508 should be included or not.
513 <title><systemitem>--disable-Bsymbolic</systemitem> and
514 <systemitem>--enable-Bsymbolic</systemitem></title>
517 By default, GLib uses the -Bsymbolic-functions linker
518 flag to avoid intra-library PLT jumps. A side-effect
519 of this is that it is no longer possible to override
520 internal uses of GLib functions with
521 <envvar>LD_PRELOAD</envvar>. Therefore, it may make
522 sense to turn this feature off in some situations.
523 The <option>--disable-Bsymbolic</option> option allows
529 <title><systemitem>--disable-gtk-doc</systemitem> and
530 <systemitem>--enable-gtk-doc</systemitem></title>
533 By default the <command>configure</command> script will try
534 to auto-detect whether the
535 <application>gtk-doc</application> package is installed. If
536 it is, then it will use it to extract and build the
537 documentation for the GLib library. These options
538 can be used to explicitly control whether
539 <application>gtk-doc</application> should be
540 used or not. If it is not used, the distributed,
541 pre-generated HTML files will be installed instead of
542 building them on your machine.
547 <title><systemitem>--disable-man</systemitem> and
548 <systemitem>--enable-man</systemitem></title>
551 By default the <command>configure</command> script will try
552 to auto-detect whether <application>xsltproc</application>
553 and the necessary Docbook stylesheets are installed. If
554 they are, then it will use them to rebuild the included
555 man pages from the XML sources. These options can be used
556 to explicitly control whether man pages should be rebuilt
557 used or not. The distribution includes pre-generated man
563 <title><systemitem>--disable-xattr</systemitem> and
564 <systemitem>--enable-xattr</systemitem></title>
567 By default the <command>configure</command> script will try
568 to auto-detect whether the getxattr() family of functions
569 is available. If it is, then extended attribute support
570 will be included in GIO. These options can be used to
571 explicitly control whether extended attribute support
572 should be included or not. getxattr() and friends can
573 be provided by glibc or by the standalone libattr library.
578 <title><systemitem>--disable-selinux</systemitem> and
579 <systemitem>--enable-selinux</systemitem></title>
582 By default the <command>configure</command> script will
583 auto-detect if libselinux is available and include
584 SELinux support in GIO if it is. These options can be
585 used to explicitly control whether SELinux support should
591 <title><systemitem>--disable-dtrace</systemitem> and
592 <systemitem>--enable-dtrace</systemitem></title>
595 By default the <command>configure</command> script will
596 detect if DTrace support is available, and use it.
601 <title><systemitem>--disable-systemtap</systemitem> and
602 <systemitem>--enable-systemtap</systemitem></title>
605 This option requires DTrace support. If it is available, then
606 the <command>configure</command> script will also check for
607 the presence of SystemTap.
612 <title><systemitem>--enable-gcov</systemitem> and
613 <systemitem>--disable-gcov</systemitem></title>
616 Enable the generation of coverage reports for the GLib tests.
617 This requires the lcov frontend to gcov from the
618 <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
619 To generate a coverage report, use the lcov make target. The
620 report is placed in the <filename>glib-lcov</filename> directory.
625 <title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title>
628 Allows specifying a relative path to where to install the runtime
629 libraries (meaning library files used for running, not developing,
630 GLib applications). This can be used in operating system setups where
631 programs using GLib needs to run before e.g. <filename>/usr</filename>
633 For example, if LIBDIR is <filename>/usr/lib</filename> and
634 <filename>../../lib</filename> is passed to
635 <systemitem>--with-runtime-libdir</systemitem> then the
636 runtime libraries are installed into <filename>/lib</filename> rather
637 than <filename>/usr/lib</filename>.