docs/reference/glib/building.sgml

   1 <refentry id="glib-building" revision="16 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Compiling the GLib package</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GLib Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Compiling the GLib Package</refname>
  10 <refpurpose>
  11 How to compile GLib itself
  12 </refpurpose>
  13   </refnamediv>
  14
  15     <refsect1 id="building">
  16       <title>Building the Library on UNIX</title>
  17       <para>
  18         On UNIX, GLib uses the standard GNU build system,
  19         using <application>autoconf</application> for package
  20         configuration and resolving portability issues,
  21         <application>automake</application> for building makefiles
  22         that comply with the GNU Coding Standards, and
  23         <application>libtool</application> for building shared
  24         libraries on multiple platforms.  The normal sequence for
  25         compiling and installing the GLib library is thus:
  26
  27         <literallayout>
  28           <userinput>./configure</userinput>
  29           <userinput>make</userinput>
  30           <userinput>make install</userinput>
  31         </literallayout>
  32       </para>
  33
  34       <para>
  35         The standard options provided by <application>GNU
  36         autoconf</application> may be passed to the
  37         <command>configure</command> script.  Please see the
  38         <application>autoconf</application> documentation or run
  39         <command>./configure --help</command> for information about
  40         the standard options.
  41       </para>
  42       <para>
  43         The GTK+ documentation contains
  44         <ulink url="../gtk/gtk-building.html">further details</ulink>
  45         about the build process and ways to influence it.
  46       </para>
  47     </refsect1>
  48     <refsect1 id="dependencies">
  49       <title>Dependencies</title>
  50       <para>
  51         Before you can compile the GLib library, you need to have
  52         various other tools and libraries installed on your
  53         system. The two tools needed during the build process (as
  54         differentiated from the tools used in when creating GLib
  55         mentioned above such as <application>autoconf</application>)
  56         are <command>pkg-config</command> and GNU make.
  57       </para>
  58       <itemizedlist>
  59         <listitem>
  60           <para>
  61             <ulink
  62             url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
  63             is a tool for tracking the compilation flags needed for
  64             libraries that are used by the GLib library. (For each
  65             library, a small <literal>.pc</literal> text file is
  66             installed in a standard location that contains the compilation
  67             flags needed for that library along with version number
  68             information.)  The version of <command>pkg-config</command>
  69             needed to build GLib is mirrored in the
  70             <filename>dependencies</filename> directory
  71             on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP
  72             site.</ulink>
  73           </para>
  74         </listitem>
  75         <listitem>
  76           <para>
  77             The GTK+ makefiles will mostly work with different versions
  78             of <command>make</command>, however, there tends to be
  79             a few incompatibilities, so the GTK+ team recommends
  80             installing <ulink url="http://www.gnu.org/software/make">GNU
  81             make</ulink> if you don't already have it on your system
  82             and using it. (It may be called <command>gmake</command>
  83             rather than <command>make</command>.)
  84           </para>
  85         </listitem>
  86       </itemizedlist>
  87       <para>
  88         GLib depends on a number of other libraries.
  89       </para>
  90       <itemizedlist>
  91         <listitem>
  92           <para>
  93           The <ulink url="http://www.gnu.org/software/libiconv/">GNU
  94           libiconv library</ulink> is needed to build GLib if your
  95           system doesn't have the <function>iconv()</function>
  96           function for doing conversion between character
  97           encodings. Most modern systems should have
  98           <function>iconv()</function>, however many older systems lack
  99           an <function>iconv()</function> implementation. On such systems,
 100           you must install the libiconv library. This can be found at:
 101           <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
 102         </para>
 103         <para>
 104           If your system has an <function>iconv()</function> implementation but
 105           you want to use libiconv instead, you can pass the
 106           --with-libiconv option to configure. This forces
 107           libiconv to be used.
 108         </para>
 109         <para>
 110           Note that if you have libiconv installed in your default include
 111           search path (for instance, in <filename>/usr/local/</filename>), but
 112           don't enable it, you will get an error while compiling GLib because
 113           the <filename>iconv.h</filename> that libiconv installs hides the
 114           system iconv.
 115         </para>
 116         <para>
 117           If you are using the native iconv implementation on Solaris
 118           instead of libiconv, you'll need to make sure that you have
 119           the converters between locale encodings and UTF-8 installed.
 120           At a minimum you'll need the SUNWuiu8 package. You probably
 121           should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
 122           SUNWkiu8 packages.
 123         </para>
 124         <para>
 125           The native iconv on Compaq Tru64 doesn't contain support for
 126           UTF-8, so you'll need to use GNU libiconv instead. (When
 127           using GNU libiconv for GLib, you'll need to use GNU libiconv
 128           for GNU gettext as well.) This probably applies to related
 129           operating systems as well.
 130         </para>
 131       </listitem>
 132       <listitem>
 133         <para>
 134           The libintl library from the <ulink
 135           url="http://www.gtk.org/software/gettext">GNU gettext
 136           package</ulink> is needed if your system doesn't have the
 137           <function>gettext()</function> functionality for handling
 138           message translation databases.
 139         </para>
 140       </listitem>
 141       <listitem>
 142         <para>
 143           A thread implementation is needed, unless you want to compile GLib
 144           without thread support, which is not recommended. The thread support
 145           in GLib can be based upon several native thread implementations,
 146           e.g. POSIX threads, DCE threads or Solaris threads.
 147         </para>
 148       </listitem>
 149       <listitem>
 150         <para>
 151           GRegex uses the the <ulink url="http://www.pcre.org/">PCRE library</ulink>
 152           for regular expression matching. The default is to use the internal
 153           version of PCRE that is patched to use GLib for memory management
 154           and Unicode handling. If you prefer to use the system-supplied PCRE
 155           library  you can pass the --with-pcre=system option to configure,
 156           but it is not recommended.
 157         </para>
 158       </listitem>
 159     </itemizedlist>
 160
 161     </refsect1>
 162     <refsect1 id="extra-configuration-options">
 163       <title>Extra Configuration Options</title>
 164
 165       <para>
 166         In addition to the normal options, the
 167         <command>configure</command> script in the GLib
 168         library supports these additional arguments:
 169
 170         <cmdsynopsis>
 171           <command>configure</command>
 172           <group>
 173             <arg>--enable-debug=[no|minimum|yes]</arg>
 174           </group>
 175           <group>
 176             <arg>--disable-gc-friendly</arg>
 177             <arg>--enable-gc-friendly</arg>
 178           </group>
 179           <group>
 180             <arg>--disable-mem-pools</arg>
 181             <arg>--enable-mem-pools</arg>
 182           </group>
 183           <group>
 184             <arg>--disable-threads</arg>
 185             <arg>--enable-threads</arg>
 186           </group>
 187           <group>
 188             <arg>--with-threads=[none|posix|dce|win32]</arg>
 189           </group>
 190           <group>
 191             <arg>--disable-regex</arg>
 192             <arg>--enable-regex</arg>
 193           </group>
 194           <group>
 195             <arg>--with-pcre=[internal|system]</arg>
 196           </group>
 197           <group>
 198              <arg>--disable-included-printf</arg>
 199              <arg>--enable-included-printf</arg>
 200           </group>
 201           <group>
 202              <arg>--disable-visibility</arg>
 203              <arg>--enable-visibility</arg>
 204           </group>
 205           <group>
 206             <arg>--disable-gtk-doc</arg>
 207             <arg>--enable-gtk-doc</arg>
 208           </group>
 209           <group>
 210             <arg>--disable-man</arg>
 211             <arg>--enable-man</arg>
 212           </group>
 213         </cmdsynopsis>
 214       </para>
 215
 216       <formalpara>
 217         <title><systemitem>--enable-debug</systemitem></title>
 218
 219         <para>
 220          Turns on various amounts of debugging support. Setting this to 'no'
 221          disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
 222          all cast checks between different object types. Setting it to 'minimum'         disables only cast checks. Setting it to 'yes' enables
 223          <link linkend="GLIB-Debug-Options">runtime debugging</link>.
 224          The default is 'minimum'.
 225          Note that 'no' is fast, but dangerous as it tends to destabilize
 226          even mostly bug-free software by changing the effect of many bugs
 227          from simple warnings into fatal crashes. Thus
 228          <option>--enable-debug=no</option> should <emphasis>not</emphasis>
 229          be used for stable releases of GLib.
 230         </para>
 231       </formalpara>
 232
 233       <formalpara>
 234         <title><systemitem>--disable-gc-friendly</systemitem> and
 235           <systemitem>--enable-gc-friendly</systemitem></title>
 236
 237         <para>
 238           By default, and with <systemitem>--disable-gc-friendly</systemitem>
 239           as well, Glib does not clear the memory for certain objects before they
 240           are freed.  For example, Glib may decide to recycle GList nodes by
 241           putting them in a free list.  However, memory profiling and debugging tools like <ulink
 242           url="http://www.valgrind.org">Valgrind</ulink> work better if an
 243           application does not keep dangling pointers to freed memory (even
 244           though these pointers are no longer dereferenced), or invalid pointers inside
 245           uninitialized memory.   The
 246           <systemitem>--enable-gc-friendly</systemitem> option makes Glib clear
 247           memory in these situations:
 248         </para>
 249       </formalpara>
 250
 251       <itemizedlist>
 252         <listitem>
 253           <para>
 254             When shrinking a GArray, Glib will clear the memory no longer
 255             available in the array:  shrink an array from 10 bytes to 7, and
 256             the last 3 bytes will be cleared.  This includes removals of single and multiple elements.
 257           </para>
 258         </listitem>
 259         <listitem>
 260           <para>
 261           </para>
 262         </listitem>
 263         <listitem>
 264           <para>
 265             When growing a GArray, Glib will clear the new chunk of memory.
 266             Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will be cleared.
 267           </para>
 268         </listitem>
 269         <listitem>
 270           <para>
 271             The above applies to GPtrArray as well.
 272           </para>
 273         </listitem>
 274         <listitem>
 275           <para>
 276             When freeing a node from a GHashTable, Glib will first clear
 277             the node, which used to have pointers to the key and the value
 278             stored at that node.
 279           </para>
 280         </listitem>
 281         <listitem>
 282           <para>
 283             When destroying or removing a GTree node, Glib will clear the node,
 284             which used to have pointers to the node's value, and the left and right subnodes.
 285           </para>
 286         </listitem>
 287       </itemizedlist>
 288
 289       <para>
 290         Since clearing the memory has a cost,
 291         <systemitem>--disable-gc-friendly</systemitem> is the default.
 292       </para>
 293
 294       <formalpara>
 295         <title><systemitem>--disable-mem-pools</systemitem> and
 296           <systemitem>--enable-mem-pools</systemitem></title>
 297
 298       <para>
 299         Many small chunks of memory are often allocated via collective pools
 300         in GLib and are cached after release to speed up reallocations.
 301         For sparse memory systems this behaviour is often inferior, so
 302         memory pools can be disabled to avoid excessive caching and force
 303         atomic maintenance of chunks through the <function>g_malloc()</function>
 304         and <function>g_free()</function> functions. Code currently affected by
 305         this:
 306         <itemizedlist>
 307         <listitem>
 308         <para>
 309          <structname>GList</structname>, <structname>GSList</structname>,
 310          <structname>GNode</structname>, <structname>GHash</structname>
 311          allocations. The functions g_list_push_allocator(),
 312          g_list_pop_allocator(), g_slist_push_allocator(),
 313          g_slist_pop_allocator(), g_node_push_allocator() and
 314          g_node_pop_allocator() are not available
 315         </para>
 316         </listitem>
 317         <listitem>
 318         <para>
 319         <structname>GMemChunk</structname>s become basically non-effective
 320         </para>
 321         </listitem>
 322         <listitem>
 323         <para>
 324          <structname>GSignal</structname> disables all caching (potentially
 325          very slow)
 326         </para>
 327         </listitem>
 328         <listitem>
 329         <para>
 330          <structname>GType</structname> doesn't honour the
 331          <structname>GTypeInfo</structname>
 332          <structfield>n_preallocs</structfield> field anymore
 333         </para>
 334         </listitem>
 335         <listitem>
 336         <para>
 337          the <structname>GBSearchArray</structname> flag
 338          <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
 339         </para>
 340         </listitem>
 341         </itemizedlist>
 342       </para>
 343       </formalpara>
 344
 345       <formalpara>
 346         <title><systemitem>--disable-threads</systemitem> and
 347           <systemitem>--enable-threads</systemitem></title>
 348
 349         <para>
 350            Do not compile GLib to be multi thread safe. GLib
 351            will be slightly faster then. This is however not
 352            recommended, as many programs rely on GLib being
 353            multi thread safe.
 354         </para>
 355       </formalpara>
 356
 357       <formalpara>
 358         <title><systemitem>--with-threads</systemitem></title>
 359
 360         <para>
 361           Specify a thread implementation to use.
 362           <itemizedlist>
 363               <listitem><para>
 364                 'posix' and 'dce' can be used interchangeable
 365                 to mean the different versions of Posix
 366                 threads. configure tries to find out, which
 367                 one is installed.
 368               </para></listitem>
 369
 370               <listitem><para>
 371                 'none' means that GLib will be thread safe,
 372                 but does not have a default thread
 373                 implementation. This has to be supplied to
 374                 <function>g_thread_init()</function> by the programmer.
 375               </para></listitem>
 376         </itemizedlist>
 377
 378         </para>
 379       </formalpara>
 380
 381       <formalpara>
 382         <title><systemitem>--disable-regex</systemitem> and
 383           <systemitem>--enable-regex</systemitem></title>
 384
 385         <para>
 386            Do not compile GLib with regular expression support.
 387            GLib will be smaller because it will not need the
 388            PCRE library. This is however not recommended, as
 389            programs may need GRegex.
 390         </para>
 391       </formalpara>
 392
 393       <formalpara>
 394         <title><systemitem>--with-pcre</systemitem></title>
 395
 396         <para>
 397           Specify whether to use the internal or the system-supplied
 398           PCRE library.
 399           <itemizedlist>
 400             <listitem><para>
 401               'internal' means that GRegex will be compiled to use
 402               the internal PCRE library.
 403             </para></listitem>
 404
 405             <listitem><para>
 406               'system' means that GRegex will be compiled to use
 407               the system-supplied PCRE library.
 408             </para></listitem>
 409           </itemizedlist>
 410           Using the internal PCRE is the preferred solution:
 411           <itemizedlist>
 412             <listitem>
 413               <para>
 414                 System-supplied PCRE has a separated copy of the big tables
 415                 used for Unicode handling.
 416               </para>
 417             </listitem>
 418             <listitem>
 419               <para>
 420                 Some systems have PCRE libraries compiled without some needed
 421                 features, such as UTF-8 and Unicode support.
 422               </para>
 423             </listitem>
 424             <listitem>
 425               <para>
 426                 PCRE uses some global variables for memory management and
 427                 other features. In the rare case of a program using both
 428                 GRegex and PCRE (maybe indirectly through a library),
 429                 this variables could lead to problems when they are modified.
 430               </para>
 431             </listitem>
 432           </itemizedlist>
 433         </para>
 434       </formalpara>
 435
 436       <formalpara>
 437          <title><systemitem>--disable-included-printf</systemitem> and
 438            <systemitem>--enable-included-printf</systemitem></title>
 439
 440         <para>
 441           By default the <command>configure</command> script will try
 442           to auto-detect whether the C library provides a suitable set
 443           of <function>printf()</function> functions. In detail,
 444           <command>configure</command> checks that the semantics of
 445           <function>snprintf()</function> are as specified by C99 and
 446           that positional parameters as specified in the Single Unix
 447           Specification are supported. If this not the case, GLib will
 448           include an implementation of the <function>printf()</function>
 449           family.
 450           These options can be used to explicitly control whether
 451           an implementation fo the <function>printf()</function> family
 452           should be included or not.
 453         </para>
 454       </formalpara>
 455
 456       <formalpara>
 457          <title><systemitem>--disable-visibility</systemitem> and
 458            <systemitem>--enable-visibility</systemitem></title>
 459
 460         <para>
 461           By default, GLib uses ELF visibility attributes to optimize
 462           PLT table entries if the compiler supports ELF visibility
 463           attributes. A side-effect of the way in which this is currently
 464           implemented is that any  header change forces a full
 465           recompilation, and missing includes may go unnoticed.
 466           Therefore, it makes sense to turn this feature off while
 467           doing GLib development, even if the compiler supports ELF
 468           visibility attributes. The <option>--disable-visibility</option>
 469           option allows to do that.
 470         </para>
 471       </formalpara>
 472
 473       <formalpara>
 474         <title><systemitem>--disable-gtk-doc</systemitem> and
 475           <systemitem>--enable-gtk-doc</systemitem></title>
 476
 477         <para>
 478           By default the <command>configure</command> script will try
 479           to auto-detect whether the
 480           <application>gtk-doc</application> package is installed.  If
 481           it is, then it will use it to extract and build the
 482           documentation for the GLib library.  These options
 483           can be used to explicitly control whether
 484           <application>gtk-doc</application> should be
 485           used or not.  If it is not used, the distributed,
 486           pre-generated HTML files will be installed instead of
 487           building them on your machine.
 488         </para>
 489       </formalpara>
 490
 491       <formalpara>
 492         <title><systemitem>--disable-man</systemitem> and
 493           <systemitem>--enable-man</systemitem></title>
 494
 495         <para>
 496           By default the <command>configure</command> script will try
 497           to auto-detect whether <application>xsltproc</application>
 498           and the necessary Docbook stylesheets are installed.  If
 499           they are, then it will use them to rebuild the included
 500           man pages from the XML sources.  These options can be used
 501           to explicitly control whether man pages should be rebuilt
 502           used or not. The distribution includes pre-generated man
 503           pages.
 504         </para>
 505       </formalpara>
 506
 507    </refsect1>
 508
 509 </refentry>