docs/reference/glib/building.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 ]>
   5 <refentry id="glib-building">
   6   <refmeta>
   7     <refentrytitle>Compiling the GLib package</refentrytitle>
   8     <manvolnum>3</manvolnum>
   9     <refmiscinfo>GLib Library</refmiscinfo>
  10   </refmeta>
  11
  12   <refnamediv>
  13     <refname>Compiling the GLib Package</refname>
  14     <refpurpose>How to compile GLib itself</refpurpose>
  15   </refnamediv>
  16
  17   <refsect1 id="building">
  18     <title>Building the Library on UNIX</title>
  19     <para>
  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:
  28
  29       <literallayout>
  30         <userinput>./configure</userinput>
  31         <userinput>make</userinput>
  32         <userinput>make install</userinput>
  33       </literallayout>
  34     </para>
  35
  36     <para>
  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
  42       the standard options.
  43     </para>
  44     <para>
  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.
  48     </para>
  49   </refsect1>
  50   <refsect1 id="dependencies">
  51     <title>Dependencies</title>
  52     <para>
  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.
  59     </para>
  60     <itemizedlist>
  61       <listitem>
  62         <para>
  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
  73           site.</ulink>
  74         </para>
  75       </listitem>
  76       <listitem>
  77         <para>
  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>.)
  85         </para>
  86       </listitem>
  87     </itemizedlist>
  88     <para>
  89       GLib depends on a number of other libraries.
  90     </para>
  91     <itemizedlist>
  92       <listitem>
  93         <para>
  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>.
 103         </para>
 104         <para>
 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
 108           libiconv to be used.
 109         </para>
 110         <para>
 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
 115           system iconv.
 116         </para>
 117         <para>
 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
 123           SUNWkiu8 packages.
 124         </para>
 125         <para>
 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.
 131         </para>
 132       </listitem>
 133       <listitem>
 134         <para>
 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.
 140         </para>
 141       </listitem>
 142       <listitem>
 143         <para>
 144           A thread implementation is needed. The thread support in GLib
 145           can be based upon POSIX threads or win32 threads.
 146         </para>
 147       </listitem>
 148       <listitem>
 149         <para>
 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.
 156         </para>
 157       </listitem>
 158       <listitem>
 159         <para>
 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>
 164           option.
 165         </para>
 166       </listitem>
 167       <listitem>
 168         <para>
 169           The optional SELinux support in GIO requires libselinux.
 170           To build GLib without SELinux support, use the
 171           <option>--disable-selinux</option> option.
 172         </para>
 173       </listitem>
 174       <listitem>
 175         <para>
 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.
 180         </para>
 181       </listitem>
 182       <listitem>
 183         <para>
 184           The optional support for
 185           <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
 186           can be disabled with the <option>--disable-systemtap</option>
 187           configure option.
 188         </para>
 189       </listitem>
 190     </itemizedlist>
 191
 192   </refsect1>
 193   <refsect1 id="extra-configuration-options">
 194     <title>Extra Configuration Options</title>
 195
 196     <para>
 197       In addition to the normal options, the
 198       <command>configure</command> script in the GLib
 199       library supports these additional arguments:
 200     </para>
 201
 202     <formalpara>
 203       <title><systemitem>--enable-debug</systemitem></title>
 204
 205       <para>
 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.
 216       </para>
 217     </formalpara>
 218
 219     <formalpara>
 220       <title><systemitem>--disable-gc-friendly</systemitem> and
 221         <systemitem>--enable-gc-friendly</systemitem></title>
 222
 223       <para>
 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:
 234       </para>
 235
 236       <itemizedlist>
 237         <listitem>
 238           <para>
 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.
 243           </para>
 244         </listitem>
 245         <listitem>
 246           <para>
 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
 249             be cleared.
 250           </para>
 251         </listitem>
 252         <listitem>
 253           <para>
 254             The above applies to GPtrArray as well.
 255           </para>
 256         </listitem>
 257         <listitem>
 258           <para>
 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
 261             stored at that node.
 262           </para>
 263         </listitem>
 264         <listitem>
 265           <para>
 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
 268             right subnodes.
 269           </para>
 270         </listitem>
 271       </itemizedlist>
 272
 273       <para>
 274         Since clearing the memory has a cost,
 275         <systemitem>--disable-gc-friendly</systemitem> is the default.
 276       </para>
 277     </formalpara>
 278
 279     <formalpara>
 280       <title><systemitem>--disable-mem-pools</systemitem> and
 281         <systemitem>--enable-mem-pools</systemitem></title>
 282
 283       <para>
 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
 290         this:
 291         <itemizedlist>
 292           <listitem>
 293             <para>
 294               <structname>GMemChunk</structname>s become basically non-effective
 295             </para>
 296           </listitem>
 297           <listitem>
 298             <para>
 299               <structname>GSignal</structname> disables all caching
 300               (potentially very slow)
 301             </para>
 302           </listitem>
 303           <listitem>
 304             <para>
 305               <structname>GType</structname> doesn't honour the
 306               <structname>GTypeInfo</structname>
 307               <structfield>n_preallocs</structfield> field anymore
 308             </para>
 309           </listitem>
 310           <listitem>
 311             <para>
 312               the <structname>GBSearchArray</structname> flag
 313               <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
 314             </para>
 315           </listitem>
 316         </itemizedlist>
 317       </para>
 318     </formalpara>
 319
 320     <formalpara>
 321       <title><systemitem>--with-threads</systemitem></title>
 322
 323       <para>
 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.
 327       </para>
 328     </formalpara>
 329
 330     <formalpara>
 331       <title><systemitem>--disable-regex</systemitem> and
 332         <systemitem>--enable-regex</systemitem></title>
 333
 334       <para>
 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.
 339       </para>
 340     </formalpara>
 341
 342     <formalpara>
 343       <title><systemitem>--with-pcre</systemitem></title>
 344
 345       <para>
 346         Specify whether to use the internal or the system-supplied
 347         PCRE library.
 348         <itemizedlist>
 349           <listitem>
 350             <para>
 351               'internal' means that GRegex will be compiled to use
 352               the internal PCRE library.
 353             </para>
 354           </listitem>
 355           <listitem>
 356             <para>
 357               'system' means that GRegex will be compiled to use
 358               the system-supplied PCRE library.
 359             </para>
 360           </listitem>
 361         </itemizedlist>
 362         Using the internal PCRE is the preferred solution:
 363         <itemizedlist>
 364           <listitem>
 365             <para>
 366               System-supplied PCRE has a separated copy of the big tables
 367               used for Unicode handling.
 368             </para>
 369           </listitem>
 370           <listitem>
 371             <para>
 372               Some systems have PCRE libraries compiled without some needed
 373               features, such as UTF-8 and Unicode support.
 374             </para>
 375           </listitem>
 376           <listitem>
 377             <para>
 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.
 382             </para>
 383           </listitem>
 384         </itemizedlist>
 385       </para>
 386     </formalpara>
 387
 388     <formalpara>
 389       <title><systemitem>--disable-included-printf</systemitem> and
 390         <systemitem>--enable-included-printf</systemitem></title>
 391
 392       <para>
 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.
 400       </para>
 401       <para>
 402         These options can be used to explicitly control whether
 403         an implementation fo the printf() family should be included or not.
 404       </para>
 405     </formalpara>
 406
 407     <formalpara>
 408       <title><systemitem>--disable-Bsymbolic</systemitem> and
 409         <systemitem>--enable-Bsymbolic</systemitem></title>
 410
 411       <para>
 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
 419         to do that.
 420       </para>
 421     </formalpara>
 422
 423     <formalpara>
 424       <title><systemitem>--disable-gtk-doc</systemitem> and
 425         <systemitem>--enable-gtk-doc</systemitem></title>
 426
 427       <para>
 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.
 438       </para>
 439     </formalpara>
 440
 441     <formalpara>
 442       <title><systemitem>--disable-man</systemitem> and
 443         <systemitem>--enable-man</systemitem></title>
 444
 445       <para>
 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
 453         pages.
 454       </para>
 455     </formalpara>
 456
 457     <formalpara>
 458       <title><systemitem>--disable-xattr</systemitem> and
 459         <systemitem>--enable-xattr</systemitem></title>
 460
 461       <para>
 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.
 469       </para>
 470     </formalpara>
 471
 472     <formalpara>
 473       <title><systemitem>--disable-selinux</systemitem> and
 474         <systemitem>--enable-selinux</systemitem></title>
 475
 476       <para>
 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
 481         be included.
 482       </para>
 483     </formalpara>
 484
 485     <formalpara>
 486       <title><systemitem>--disable-dtrace</systemitem> and
 487         <systemitem>--enable-dtrace</systemitem></title>
 488
 489       <para>
 490         By default the <command>configure</command> script will
 491         detect if DTrace support is available, and use it.
 492       </para>
 493     </formalpara>
 494
 495     <formalpara>
 496       <title><systemitem>--disable-systemtap</systemitem> and
 497         <systemitem>--enable-systemtap</systemitem></title>
 498
 499       <para>
 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.
 503       </para>
 504     </formalpara>
 505
 506     <formalpara>
 507       <title><systemitem>--enable-gcov</systemitem> and
 508         <systemitem>--disable-gcov</systemitem></title>
 509
 510       <para>
 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.
 516       </para>
 517     </formalpara>
 518
 519     <formalpara>
 520       <title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title>
 521
 522       <para>
 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>
 527         is mounted.
 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>.
 533       </para>
 534     </formalpara>
 535
 536   </refsect1>
 537
 538 </refentry>