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     </itemizedlist>
 150
 151     </refsect1>
 152     <refsect1 id="extra-configuration-options">
 153       <title>Extra Configuration Options</title>
 154
 155       <para>
 156         In addition to the normal options, the
 157         <command>configure</command> script in the GLib
 158         library supports these additional arguments:
 159
 160         <cmdsynopsis>
 161           <command>configure</command>
 162           <group>
 163             <arg>--enable-debug=[no|minimum|yes]</arg>
 164           </group>
 165           <group>
 166             <arg>--disable-gc-friendly</arg>
 167             <arg>--enable-gc-friendly</arg>
 168           </group>
 169           <group>
 170             <arg>--disable-mem-pools</arg>
 171             <arg>--enable-mem-pools</arg>
 172           </group>
 173           <group>
 174             <arg>--disable-threads</arg>
 175             <arg>--enable-threads</arg>
 176           </group>
 177           <group>
 178             <arg>--with-threads=[none|posix|dce|solaris|win32]</arg>
 179           </group>
 180           <group>
 181              <arg>--disable-included-printf</arg>
 182              <arg>--enable-included-printf</arg>
 183           </group>
 184           <group>
 185             <arg>--disable-gtk-doc</arg>
 186             <arg>--enable-gtk-doc</arg>
 187           </group>
 188         </cmdsynopsis>
 189       </para>
 190
 191       <formalpara>
 192         <title><systemitem>--enable-debug</systemitem></title>
 193
 194         <para>
 195          Turns on various amounts of debugging support. Setting this to 'no'
 196          disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
 197          all cast checks between different object types. Setting it to 'minimum'         disables only cast checks. Setting it to 'yes' enables
 198          <link linkend="GLIB-Debug-Options">runtime debugging</link>.
 199          The default is 'minimum'.
 200          Note that 'no' is fast, but dangerous as it tends to destabilize
 201          even mostly bug-free software by changing the effect of many bugs
 202          from simple warnings into fatal crashes. Thus
 203          <option>--enable-debug=no</option> should <emphasis>not</emphasis>
 204          be used for stable releases of GLib.
 205         </para>
 206       </formalpara>
 207
 208       <formalpara>
 209         <title><systemitem>--disable-gc-friendly</systemitem> and
 210           <systemitem>--enable-gc-friendly</systemitem></title>
 211
 212         <para>
 213           When enabled all memory freed by the application,
 214           but retained by GLib for performance reasons
 215           is set to zero, thus making deployed garbage
 216           collection or memory profiling tools detect
 217           unlinked memory correctly. This will make GLib
 218           slightly slower and is thus disabled by default.
 219         </para>
 220       </formalpara>
 221
 222       <formalpara>
 223         <title><systemitem>--disable-mem-pools</systemitem> and
 224           <systemitem>--enable-mem-pools</systemitem></title>
 225
 226       <para>
 227         Many small chunks of memory are often allocated via collective pools
 228         in GLib and are cached after release to speed up reallocations.
 229         For sparse memory systems this behaviour is often inferior, so
 230         memory pools can be disabled to avoid excessive caching and force
 231         atomic maintenance of chunks through the <function>g_malloc()</function>
 232         and <function>g_free()</function> functions. Code currently affected by
 233         this:
 234         <itemizedlist>
 235         <listitem>
 236         <para>
 237          <structname>GList</structname>, <structname>GSList</structname>,
 238          <structname>GNode</structname>, <structname>GHash</structname>
 239          allocations
 240         </para>
 241         </listitem>
 242         <listitem>
 243         <para>
 244         <structname>GMemChunk</structname>s become basically non-effective
 245         </para>
 246         </listitem>
 247         <listitem>
 248         <para>
 249          <structname>GSignal</structname> disables all caching (potentially
 250          very slow)
 251         </para>
 252         </listitem>
 253         <listitem>
 254         <para>
 255          <structname>GType</structname> doesn't honour the
 256          <structname>GTypeInfo</structname>
 257          <structfield>n_preallocs</structfield> field anymore
 258         </para>
 259         </listitem>
 260         <listitem>
 261         <para>
 262          the <structname>GBSearchArray</structname> flag
 263          <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
 264         </para>
 265         </listitem>
 266         </itemizedlist>
 267       </para>
 268       </formalpara>
 269
 270       <formalpara>
 271         <title><systemitem>--disable-threads</systemitem> and
 272           <systemitem>--enable-threads</systemitem></title>
 273
 274         <para>
 275            Do not compile GLib to be multi thread safe. GLib
 276            will be slightly faster then. This is however not
 277            recommended, as many programs rely on GLib being
 278            multi thread safe.
 279         </para>
 280       </formalpara>
 281
 282       <formalpara>
 283         <title><systemitem>--with-threads</systemitem></title>
 284
 285         <para>
 286           Specify a thread implementation to use.
 287           <itemizedlist>
 288               <listitem><para>
 289                 'posix' and 'dce' can be used interchangeable
 290                 to mean the different versions of Posix
 291                 threads. configure tries to find out, which
 292                 one is installed.
 293               </para></listitem>
 294
 295               <listitem><para>
 296                 'solaris' uses the native Solaris thread implementation.
 297               </para></listitem>
 298
 299               <listitem><para>
 300                 'none' means that GLib will be thread safe,
 301                 but does not have a default thread
 302                 implementation. This has to be supplied to
 303                 <function>g_thread_init()</function> by the programmer.
 304               </para></listitem>
 305         </itemizedlist>
 306
 307         </para>
 308       </formalpara>
 309
 310       <formalpara>
 311          <title><systemitem>--disable-included-printf</systemitem> and
 312            <systemitem>--enable-included-printf</systemitem></title>
 313
 314         <para>
 315           By default the <command>configure</command> script will try
 316           to auto-detect whether the C library provides a suitable set
 317           of <function>printf()</function> functions. In detail,
 318           <command>configure</command> checks that the semantics of
 319           <function>snprintf()</function> are as specified by C99 and
 320           that positional parameters as specified in the Single Unix
 321           Specification are supported. If this not the case, GLib will
 322           include an implementation of the <function>printf()</function>
 323           family.
 324           These options can be used to explicitly control whether
 325           an implementation fo the <function>printf()</function> family
 326           should be included or not.
 327         </para>
 328       </formalpara>
 329
 330       <formalpara>
 331         <title><systemitem>--disable-gtk-doc</systemitem> and
 332           <systemitem>--enable-gtk-doc</systemitem></title>
 333
 334         <para>
 335           By default the <command>configure</command> script will try
 336           to auto-detect whether the
 337           <application>gtk-doc</application> package is installed.  If
 338           it is, then it will use it to extract and build the
 339           documentation for the GLib library.  These options
 340           can be used to explicitly control whether
 341           <application>gtk-doc</application> should be
 342           used or not.  If it is not used, the distributed,
 343           pre-generated HTML files will be installed instead of
 344           building them on your machine.
 345         </para>
 346       </formalpara>
 347
 348    </refsect1>
 349
 350 </refentry>