mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-28 13:12:10 +01:00
e42ff0105d
Hopefully discouraging people from overriding that and building with it enabled. Pro-tip: GLib will break. Signed-off-by: Philip Withnall <withnall@endlessm.com> https://bugzilla.gnome.org/show_bug.cgi?id=791622
555 lines
22 KiB
XML
555 lines
22 KiB
XML
<?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>
|
|
GLib is compiled with
|
|
<ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
|
|
disabled. It is strongly recommended that this is not re-enabled by
|
|
overriding the compiler flags, as GLib has not been tested with strict
|
|
aliasing and cannot be guaranteed to work.
|
|
</para>
|
|
<para>
|
|
The GTK+ documentation contains
|
|
<ulink url="https://developer.gnome.org/gtk3/stable/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.
|
|
If you are building from a release archive, you will need
|
|
<ulink url="https://wiki.gnome.org/Projects/GLib/CompilerRequirements">a compliant C toolchain</ulink>,
|
|
GNU Make, and <application>pkg-config</application>;
|
|
if you are building directly from a Git repository clone
|
|
of GLib, you will also need the GNU Autotools mentioned
|
|
above.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">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).
|
|
</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
|
|
<option>--with-libiconv</option> 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 system
|
|
version of PCRE, to reduce the chances of security fixes going out
|
|
of sync. GLib additionally provides an internal copy of PCRE in case
|
|
the system version is too old, or does not support UTF-8; the internal
|
|
copy is patched to use GLib for memory management and to share the
|
|
same Unicode tables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The optional extended attribute support in GIO requires the
|
|
<function>getxattr()</function> family of functions that may be
|
|
provided by the C library 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. Additionally, you can control the location
|
|
where GLib installs the SystemTap probes, using the
|
|
<option>--with-tapset-install-dir=DIR</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><option>--enable-debug</option></title>
|
|
|
|
<para>
|
|
Turns on various amounts of debugging support. Setting this to 'no'
|
|
disables <function>g_assert()</function>, <function>g_return_if_fail()</function>,
|
|
<function>g_return_val_if_fail()</function> 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' for stable releases, and 'yes' for development
|
|
snapshots. 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><option>--disable-gc-friendly</option> and
|
|
<option>--enable-gc-friendly</option></title>
|
|
|
|
<para>
|
|
By default, and with <option>--disable-gc-friendly</option>
|
|
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 <option>--enable-gc-friendly</option> 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,
|
|
<option>--disable-gc-friendly</option> is the default.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--disable-mem-pools</option> and
|
|
<option>--enable-mem-pools</option></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><option>--with-threads</option></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><option>--with-pcre</option></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; this is the default
|
|
setting.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
Using the internal PCRE is the preferred solution if:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
your system has strict resource constraints; the system-supplied
|
|
PCRE has a separated copy of the tables used for Unicode
|
|
handling, whereas the internal copy shares the Unicode tables
|
|
used by GLib.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
your system has PCRE built without some needed features,
|
|
such as UTF-8 and Unicode support.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
you are planning to use both GRegex and PCRE API at the same
|
|
time, either directly or indirectly through a dependency; PCRE
|
|
uses some global variables for memory management and
|
|
other features, and if both GLib and PCRE try to access them
|
|
at the same time, this could lead to undefined behavior.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--disable-included-printf</option> and
|
|
<option>--enable-included-printf</option></title>
|
|
|
|
<para>
|
|
By default the <command>configure</command> script will try
|
|
to auto-detect whether the C library provides a suitable set
|
|
of <function>printf()</function> functions. In detail,
|
|
<command>configure</command> checks that the semantics of
|
|
<function>snprintf()</function> 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 <function>printf()</function>
|
|
family.
|
|
</para>
|
|
<para>
|
|
These options can be used to explicitly control whether
|
|
an implementation of the <function>printf()</function> family
|
|
should be included or not.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--disable-Bsymbolic</option> and
|
|
<option>--enable-Bsymbolic</option></title>
|
|
|
|
<para>
|
|
By default, GLib uses the <option>-Bsymbolic-functions</option>
|
|
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><option>--disable-gtk-doc</option> and
|
|
<option>--enable-gtk-doc</option></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><option>--disable-man</option> and
|
|
<option>--enable-man</option></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><option>--disable-xattr</option> and
|
|
<option>--enable-xattr</option></title>
|
|
|
|
<para>
|
|
By default the <command>configure</command> script will try
|
|
to auto-detect whether the <function>getxattr()</function>
|
|
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. <function>getxattr()</function>
|
|
and friends can be provided by glibc or by the standalone
|
|
libattr library.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--disable-selinux</option> and
|
|
<option>--enable-selinux</option></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><option>--disable-dtrace</option> and
|
|
<option>--enable-dtrace</option></title>
|
|
|
|
<para>
|
|
By default the <command>configure</command> script will
|
|
detect if DTrace support is available, and use it.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--disable-systemtap</option> and
|
|
<option>--enable-systemtap</option></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><option>--enable-coverage</option> and
|
|
<option>--disable-coverage</option></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><option>--with-runtime-libdir=RELPATH</option></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 <varname>LIBDIR</varname> is <filename>/usr/lib</filename> and
|
|
<filename>../../lib</filename> is passed to
|
|
<option>--with-runtime-libdir</option> then the
|
|
runtime libraries are installed into <filename>/lib</filename> rather
|
|
than <filename>/usr/lib</filename>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><option>--with-python=PATH</option></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.7)
|
|
or, preferably, with Python 3.
|
|
</para>
|
|
</formalpara>
|
|
</refsect1>
|
|
|
|
</refentry>
|