| <?xml version="1.0"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| ]> |
| <refentry id="glib-building"> |
| <refmeta> |
| <refentrytitle>Compiling the GLib package</refentrytitle> |
| <manvolnum>3</manvolnum> |
| <refmiscinfo>GLib Library</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>Compiling the GLib Package</refname> |
| <refpurpose>How to compile GLib itself</refpurpose> |
| </refnamediv> |
| |
| <refsect1 id="building"> |
| <title>Building the Library on UNIX</title> |
| <para> |
| On UNIX, GLib uses the standard GNU build system, |
| using <application>autoconf</application> for package |
| configuration and resolving portability issues, |
| <application>automake</application> for building makefiles |
| that comply with the GNU Coding Standards, and |
| <application>libtool</application> for building shared |
| libraries on multiple platforms. The normal sequence for |
| compiling and installing the GLib library is thus: |
| |
| <literallayout> |
| <userinput>./configure</userinput> |
| <userinput>make</userinput> |
| <userinput>make install</userinput> |
| </literallayout> |
| </para> |
| |
| <para> |
| The standard options provided by <application>GNU |
| autoconf</application> may be passed to the |
| <command>configure</command> script. Please see the |
| <application>autoconf</application> documentation or run |
| <command>./configure --help</command> for information about |
| the standard options. |
| </para> |
| <para> |
| The GTK+ documentation contains |
| <ulink url="../gtk/gtk-building.html">further details</ulink> |
| about the build process and ways to influence it. |
| </para> |
| </refsect1> |
| <refsect1 id="dependencies"> |
| <title>Dependencies</title> |
| <para> |
| Before you can compile the GLib library, you need to have |
| various other tools and libraries installed on your system. |
| Beyond a C compiler (which must implement C90, but does not need |
| to implement C99), the two tools needed during the build process |
| (as differentiated from the tools used in when creating GLib |
| mentioned above such as <application>autoconf</application>) are |
| <command>pkg-config</command> and GNU make. |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink> |
| is a tool for tracking the compilation flags needed for |
| libraries that are used by the GLib library. (For each |
| library, a small <literal>.pc</literal> text file is |
| installed in a standard location that contains the compilation |
| flags needed for that library along with version number |
| information.) The version of <command>pkg-config</command> |
| needed to build GLib is mirrored in the |
| <filename>dependencies</filename> directory |
| on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">GTK+ FTP |
| site.</ulink> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The GLib Makefiles make use of several features specific to |
| <ulink url="http://www.gnu.org/software/make">GNU |
| make</ulink>, and will not build correctly with other |
| versions of <command>make</command>. You will need to |
| install it if you don't already have it on your system. (It |
| may be called <command>gmake</command> rather than |
| <command>make</command>.) |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| A UNIX build of GLib requires that the system implements at |
| least the original 1990 version of POSIX. Beyond this, it |
| depends on a number of other libraries. |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| The <ulink url="http://www.gnu.org/software/libiconv/">GNU |
| libiconv library</ulink> is needed to build GLib if your |
| system doesn't have the <function>iconv()</function> |
| function for doing conversion between character |
| encodings. Most modern systems should have |
| <function>iconv()</function>, however many older systems lack |
| an <function>iconv()</function> implementation. On such systems, |
| you must install the libiconv library. This can be found at: |
| <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>. |
| </para> |
| <para> |
| If your system has an <function>iconv()</function> implementation but |
| you want to use libiconv instead, you can pass the |
| --with-libiconv option to configure. This forces |
| libiconv to be used. |
| </para> |
| <para> |
| Note that if you have libiconv installed in your default include |
| search path (for instance, in <filename>/usr/local/</filename>), but |
| don't enable it, you will get an error while compiling GLib because |
| the <filename>iconv.h</filename> that libiconv installs hides the |
| system iconv. |
| </para> |
| <para> |
| If you are using the native iconv implementation on Solaris |
| instead of libiconv, you'll need to make sure that you have |
| the converters between locale encodings and UTF-8 installed. |
| At a minimum you'll need the SUNWuiu8 package. You probably |
| should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and |
| SUNWkiu8 packages. |
| </para> |
| <para> |
| The native iconv on Compaq Tru64 doesn't contain support for |
| UTF-8, so you'll need to use GNU libiconv instead. (When |
| using GNU libiconv for GLib, you'll need to use GNU libiconv |
| for GNU gettext as well.) This probably applies to related |
| operating systems as well. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The libintl library from the <ulink |
| url="http://www.gnu.org/software/gettext">GNU gettext |
| package</ulink> is needed if your system doesn't have the |
| <function>gettext()</function> functionality for handling |
| message translation databases. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| A thread implementation is needed. The thread support in GLib |
| can be based upon POSIX threads or win32 threads. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink> |
| for regular expression matching. The default is to use the internal |
| version of PCRE that is patched to use GLib for memory management |
| and Unicode handling. If you prefer to use the system-supplied PCRE |
| library you can pass the <option>--with-pcre=system</option> option |
| to, but it is not recommended. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The optional extended attribute support in GIO requires the |
| getxattr() family of functions that may be provided by glibc or |
| by the standalone libattr library. To build GLib without extended |
| attribute support, use the <option>--disable-xattr</option> |
| option. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The optional SELinux support in GIO requires libselinux. |
| To build GLib without SELinux support, use the |
| <option>--disable-selinux</option> option. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The optional support for DTrace requires the |
| <filename>sys/sdt.h</filename> header, which is provided |
| by SystemTap on Linux. To build GLib without DTrace, use |
| the <option>--disable-dtrace</option> configure option. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The optional support for |
| <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> |
| can be disabled with the <option>--disable-systemtap</option> |
| configure option. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| </refsect1> |
| <refsect1 id="extra-configuration-options"> |
| <title>Extra Configuration Options</title> |
| |
| <para> |
| In addition to the normal options, the |
| <command>configure</command> script in the GLib |
| library supports these additional arguments: |
| </para> |
| |
| <formalpara> |
| <title><systemitem>--enable-debug</systemitem></title> |
| |
| <para> |
| Turns on various amounts of debugging support. Setting this to 'no' |
| disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and |
| all cast checks between different object types. Setting it to 'minimum' disables only cast checks. Setting it to 'yes' enables |
| <link linkend="G-DEBUG:CAPS">runtime debugging</link>. |
| The default is 'minimum'. |
| Note that 'no' is fast, but dangerous as it tends to destabilize |
| even mostly bug-free software by changing the effect of many bugs |
| from simple warnings into fatal crashes. Thus |
| <option>--enable-debug=no</option> should <emphasis>not</emphasis> |
| be used for stable releases of GLib. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-gc-friendly</systemitem> and |
| <systemitem>--enable-gc-friendly</systemitem></title> |
| |
| <para> |
| By default, and with <systemitem>--disable-gc-friendly</systemitem> |
| as well, Glib does not clear the memory for certain objects before |
| they are freed. For example, Glib may decide to recycle GList nodes |
| by putting them in a free list. However, memory profiling and debugging |
| tools like <ulink url="http://www.valgrind.org">Valgrind</ulink> work |
| better if an application does not keep dangling pointers to freed |
| memory (even though these pointers are no longer dereferenced), or |
| invalid pointers inside uninitialized memory. |
| The <systemitem>--enable-gc-friendly</systemitem> option makes Glib |
| clear memory in these situations: |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| When shrinking a GArray, Glib will clear the memory no longer |
| available in the array: shrink an array from 10 bytes to 7, and |
| the last 3 bytes will be cleared. This includes removals of single |
| and multiple elements. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| When growing a GArray, Glib will clear the new chunk of memory. |
| Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will |
| be cleared. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The above applies to GPtrArray as well. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| When freeing a node from a GHashTable, Glib will first clear |
| the node, which used to have pointers to the key and the value |
| stored at that node. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| When destroying or removing a GTree node, Glib will clear the node, |
| which used to have pointers to the node's value, and the left and |
| right subnodes. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| Since clearing the memory has a cost, |
| <systemitem>--disable-gc-friendly</systemitem> is the default. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-mem-pools</systemitem> and |
| <systemitem>--enable-mem-pools</systemitem></title> |
| |
| <para> |
| Many small chunks of memory are often allocated via collective pools |
| in GLib and are cached after release to speed up reallocations. |
| For sparse memory systems this behaviour is often inferior, so |
| memory pools can be disabled to avoid excessive caching and force |
| atomic maintenance of chunks through the <function>g_malloc()</function> |
| and <function>g_free()</function> functions. Code currently affected by |
| this: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <structname>GMemChunk</structname>s become basically non-effective |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <structname>GSignal</structname> disables all caching |
| (potentially very slow) |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <structname>GType</structname> doesn't honour the |
| <structname>GTypeInfo</structname> |
| <structfield>n_preallocs</structfield> field anymore |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| the <structname>GBSearchArray</structname> flag |
| <literal>G_BSEARCH_ALIGN_POWER2</literal> becomes non-functional |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--with-threads</systemitem></title> |
| |
| <para> |
| Specify a thread implementation to use. Available options are |
| 'posix' or 'win32'. Normally, <command>configure</command> |
| should be able to work out the system threads API on its own. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-regex</systemitem> and |
| <systemitem>--enable-regex</systemitem></title> |
| |
| <para> |
| Do not compile GLib with regular expression support. |
| GLib will be smaller because it will not need the |
| PCRE library. This is however not recommended, as |
| programs may need GRegex. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--with-pcre</systemitem></title> |
| |
| <para> |
| Specify whether to use the internal or the system-supplied |
| PCRE library. |
| <itemizedlist> |
| <listitem> |
| <para> |
| 'internal' means that GRegex will be compiled to use |
| the internal PCRE library. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 'system' means that GRegex will be compiled to use |
| the system-supplied PCRE library. |
| </para> |
| </listitem> |
| </itemizedlist> |
| Using the internal PCRE is the preferred solution: |
| <itemizedlist> |
| <listitem> |
| <para> |
| System-supplied PCRE has a separated copy of the big tables |
| used for Unicode handling. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Some systems have PCRE libraries compiled without some needed |
| features, such as UTF-8 and Unicode support. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| PCRE uses some global variables for memory management and |
| other features. In the rare case of a program using both |
| GRegex and PCRE (maybe indirectly through a library), |
| this variables could lead to problems when they are modified. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-included-printf</systemitem> and |
| <systemitem>--enable-included-printf</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will try |
| to auto-detect whether the C library provides a suitable set |
| of printf() functions. In detail, <command>configure</command> |
| checks that the semantics of snprintf() are as specified by C99 |
| and that positional parameters as specified in the Single Unix |
| Specification are supported. If this not the case, GLib will |
| include an implementation of the printf() family. |
| </para> |
| <para> |
| These options can be used to explicitly control whether |
| an implementation of the printf() family should be included or not. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-Bsymbolic</systemitem> and |
| <systemitem>--enable-Bsymbolic</systemitem></title> |
| |
| <para> |
| By default, GLib uses the -Bsymbolic-functions linker |
| flag to avoid intra-library PLT jumps. A side-effect |
| of this is that it is no longer possible to override |
| internal uses of GLib functions with |
| <envar>LD_PRELOAD</envar>. Therefore, it may make |
| sense to turn this feature off in some situations. |
| The <option>--disable-Bsymbolic</option> option allows |
| to do that. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-gtk-doc</systemitem> and |
| <systemitem>--enable-gtk-doc</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will try |
| to auto-detect whether the |
| <application>gtk-doc</application> package is installed. |
| If it is, then it will use it to extract and build the |
| documentation for the GLib library. These options |
| can be used to explicitly control whether |
| <application>gtk-doc</application> should be |
| used or not. If it is not used, the distributed, |
| pre-generated HTML files will be installed instead of |
| building them on your machine. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-man</systemitem> and |
| <systemitem>--enable-man</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will try |
| to auto-detect whether <application>xsltproc</application> |
| and the necessary Docbook stylesheets are installed. |
| If they are, then it will use them to rebuild the included |
| man pages from the XML sources. These options can be used |
| to explicitly control whether man pages should be rebuilt |
| used or not. The distribution includes pre-generated man |
| pages. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-xattr</systemitem> and |
| <systemitem>--enable-xattr</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will try |
| to auto-detect whether the getxattr() family of functions |
| is available. If it is, then extended attribute support |
| will be included in GIO. These options can be used to |
| explicitly control whether extended attribute support |
| should be included or not. getxattr() and friends can |
| be provided by glibc or by the standalone libattr library. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-selinux</systemitem> and |
| <systemitem>--enable-selinux</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will |
| auto-detect if libselinux is available and include |
| SELinux support in GIO if it is. These options can be |
| used to explicitly control whether SELinux support should |
| be included. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-dtrace</systemitem> and |
| <systemitem>--enable-dtrace</systemitem></title> |
| |
| <para> |
| By default the <command>configure</command> script will |
| detect if DTrace support is available, and use it. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--disable-systemtap</systemitem> and |
| <systemitem>--enable-systemtap</systemitem></title> |
| |
| <para> |
| This option requires DTrace support. If it is available, then |
| the <command>configure</command> script will also check for |
| the presence of SystemTap. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--enable-coverage</systemitem> and |
| <systemitem>--disable-coverage</systemitem></title> |
| |
| <para> |
| Enable the generation of coverage reports for the GLib tests. |
| This requires the lcov frontend to gcov from the |
| <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>. |
| To generate a coverage report, use the lcov make target. The |
| report is placed in the <filename>glib-lcov</filename> directory. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--with-runtime-libdir=RELPATH</systemitem></title> |
| |
| <para> |
| Allows specifying a relative path to where to install the runtime |
| libraries (meaning library files used for running, not developing, |
| GLib applications). This can be used in operating system setups where |
| programs using GLib needs to run before e.g. <filename>/usr</filename> |
| is mounted. |
| For example, if LIBDIR is <filename>/usr/lib</filename> and |
| <filename>../../lib</filename> is passed to |
| <systemitem>--with-runtime-libdir</systemitem> then the |
| runtime libraries are installed into <filename>/lib</filename> rather |
| than <filename>/usr/lib</filename>. |
| </para> |
| </formalpara> |
| |
| <formalpara> |
| <title><systemitem>--with-python</systemitem></title> |
| |
| <para> |
| Allows specifying the Python interpreter to use, either as an absolute path, |
| or as a program name. GLib can be built with Python 2 (at least version 2.5) |
| or Python 3. |
| </para> |
| </formalpara> |
| </refsect1> |
| |
| </refentry> |