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     </refsect1>
  43
  44     <refsect1 id="extra-configuration-options">
  45       <title>Extra Configuration Options</title>
  46
  47       <para>
  48         In addition to the normal options, the
  49         <command>configure</command> script in the GTK+
  50         library supports these additional arguments:
  51
  52         <cmdsynopsis>
  53           <command>configure</command>
  54           <group>
  55             <arg>--enable-debug=[no|minimum|yes]</arg>
  56           </group>
  57           <group>
  58             <arg>--disable-gc-friendly</arg>
  59             <arg>--enable-gc-friendly</arg>
  60           </group>
  61           <group>
  62             <arg>--disable-mem-pools</arg>
  63             <arg>--enable-mem-pools</arg>
  64           </group>
  65           <group>
  66             <arg>--disable-threads</arg>
  67             <arg>--enable-threads</arg>
  68           </group>
  69           <group>
  70             <arg>--with-threads=[none|posix|dce|solaris|win32]</arg>
  71           </group>
  72           <group>
  73             <arg>--disable-included-printf</arg>
  74             <arg>--enable-included-printf</arg>
  75           </group>
  76           <group>
  77             <arg>--disable-gtk-doc</arg>
  78             <arg>--enable-gtk-doc</arg>
  79           </group>
  80         </cmdsynopsis>
  81       </para>
  82
  83       <formalpara>
  84         <title><systemitem>--enable-debug</systemitem></title>
  85
  86         <para>
  87          Turns on various amounts of debugging support. Setting this to 'no'
  88          disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
  89          all cast checks between different object types. Setting it to 'minimum'         disables only cast checks. Setting it to 'yes' enables
  90          <link linkend="GLIB-Debug-Options">runtime debugging</link>.
  91          The default is 'minimum'.
  92          Note that 'no' is fast, but dangerous as it tends to destabilize
  93          even mostly bug-free software by changing the effect of many bugs
  94          from simple warnings into fatal crashes. Thus
  95          <option>--enable-debug=no</option> should <emphasis>not</emphasis>
  96          be used for stable releases of gtk+.
  97         </para>
  98       </formalpara>
  99
 100       <formalpara>
 101         <title><systemitem>--disable-gc-friendly</systemitem> and
 102           <systemitem>--enable-gc-friendly</systemitem></title>
 103
 104         <para>
 105           When enabled all memory freed by the application,
 106           but retained by GLib for performance reasons
 107           is set to zero, thus making deployed garbage
 108           collection or memory profiling tools detect
 109           unlinked memory correctly. This will make GLib
 110           slightly slower and is thus disabled by default.
 111         </para>
 112       </formalpara>
 113
 114       <formalpara>
 115         <title><systemitem>--disable-mem-pools</systemitem> and
 116           <systemitem>--enable-mem-pools</systemitem></title>
 117
 118       <para>
 119         Many small chunks of memory are often allocated via collective pools
 120         in GLib and are cached after release to speed up reallocations.
 121         For sparse memory systems this behaviour is often inferior, so
 122         memory pools can be disabled to avoid excessive caching and force
 123         atomic maintenance of chunks through the <function>g_malloc()</function>
 124         and <function>g_free()</function> functions. Code currently affected by
 125         this:
 126         <itemizedlist>
 127         <listitem>
 128         <para>
 129          <structname>GList</structname>, <structname>GSList</structname>,
 130          <structname>GNode</structname> allocations
 131         </para>
 132         </listitem>
 133         <listitem>
 134         <para>
 135         <structname>GMemChunk</structname>s become basically non-effective
 136         </para>
 137         </listitem>
 138         <listitem>
 139         <para>
 140          <structname>GSignal</structname> disables all caching (potentially
 141          very slow)
 142         </para>
 143         </listitem>
 144         <listitem>
 145         <para>
 146          <structname>GType</structname> doesn't honour the
 147          <structname>GTypeInfo</structname>
 148          <structfield>n_preallocs</structfield> field anymore
 149         </para>
 150         </listitem>
 151         <listitem>
 152         <para>
 153          the <structname>GBSearchArray</structname> flag
 154          <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional
 155         </para>
 156         </listitem>
 157         </itemizedlist>
 158       </para>
 159       </formalpara>
 160
 161       <formalpara>
 162         <title><systemitem>--disable-threads</systemitem> and
 163           <systemitem>--enable-threads</systemitem></title>
 164
 165         <para>
 166            Do not compile GLib to be multi thread safe. GLib
 167            will be slightly faster then. This is however not
 168            recommended, as many programs rely on GLib being
 169            multi thread safe.
 170         </para>
 171       </formalpara>
 172
 173       <formalpara>
 174         <title><systemitem>--with-threads</systemitem></title>
 175
 176         <para>
 177           Specify a thread implementation to use.
 178           <itemizedlist>
 179               <listitem><para>
 180                 'posix' and 'dce' can be used interchangeable
 181                 to mean the different versions of posix
 182                 threads. configure tries to find out, which
 183                 one is installed.
 184               </para></listitem>
 185
 186               <listitem><para>
 187                 'solaris' uses the native Solaris thread implementation.
 188               </para></listitem>
 189
 190               <listitem><para>
 191                 'none' means that GLib will be thread safe,
 192                 but does not have a default thread
 193                 implementation. This has to be supplied to
 194                 g_thread_init() by the programmer.
 195               </para></listitem>
 196         </itemizedlist>
 197
 198         </para>
 199       </formalpara>
 200
 201       <formalpara>
 202         <title><systemitem>--disable-included-printf</systemitem> and
 203           <systemitem>--enable-included-printf</systemitem></title>
 204
 205         <para>
 206           By default the <command>configure</command> script will try
 207           to auto-detect whether the C library provides a suitable set
 208           of <function>printf()</function> functions. In detail,
 209           <command>configure</command> checks that the semantics of
 210           <function>snprintf()</function> are as specified by C99 and
 211           that positional parameters as specified in the Single Unix
 212           Specification are supported. If this not the case, GLib will
 213           include an implementation of the <function>printf()</function>
 214           family.
 215           These options can be used to explicitly control whether
 216           an implementation fo the <function>printf()</function> family
 217           should be included or not.
 218         </para>
 219       </formalpara>
 220
 221       <formalpara>
 222         <title><systemitem>--disable-gtk-doc</systemitem> and
 223           <systemitem>--enable-gtk-doc</systemitem></title>
 224
 225         <para>
 226           By default the <command>configure</command> script will try
 227           to auto-detect whether the
 228           <application>gtk-doc</application> package is installed.  If
 229           it is, then it will use it to extract and build the
 230           documentation for the GLib library.  These options
 231           can be used to explicitly control whether
 232           <application>gtk-doc</application> should be
 233           used or not.  If it is not used, the distributed,
 234           pre-generated HTML files will be installed instead of
 235           building them on your machine.
 236         </para>
 237       </formalpara>
 238
 239    </refsect1>
 240
 241 </refentry>