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