[glib] Some more docs reshuffling
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Some more docs reshuffling
- Date: Sun, 13 Nov 2011 03:52:58 +0000 (UTC)
commit e60846dc78b9dace8d27276f7ef512e209dba7b3
Author: Matthias Clasen <mclasen redhat com>
Date: Sat Nov 12 22:52:24 2011 -0500
Some more docs reshuffling
docs/reference/glib/building.sgml | 980 ++++++++++++++++--------------------
docs/reference/glib/glib-docs.sgml | 132 +++---
2 files changed, 509 insertions(+), 603 deletions(-)
---
diff --git a/docs/reference/glib/building.sgml b/docs/reference/glib/building.sgml
index b888237..55c3d12 100644
--- a/docs/reference/glib/building.sgml
+++ b/docs/reference/glib/building.sgml
@@ -2,162 +2,158 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
]>
-<refentry id="glib-building" revision="16 Jan 2002">
-<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>
+<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. 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 GTK+ makefiles will mostly work with different versions
- of <command>make</command>, however, there tends to be
- a few incompatibilities, so the GTK+ team recommends
- installing <ulink url="http://www.gnu.org/software/make";>GNU
- make</ulink> if you don't already have it on your system
- and using it. (It may be called <command>gmake</command>
- rather than <command>make</command>.)
- </para>
- </listitem>
- </itemizedlist>
- <para>
- GLib 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>
+ <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. 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 GTK+ makefiles will mostly work with different versions
+ of <command>make</command>, however, there tends to be
+ a few incompatibilities, so the GTK+ team recommends
+ installing <ulink url="http://www.gnu.org/software/make";>GNU
+ make</ulink> if you don't already have it on your system
+ and using it. (It may be called <command>gmake</command>
+ rather than <command>make</command>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ GLib depends on a number of other libraries.
+ </para>
+ <itemizedlist>
+ <listitem>
<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>
+ 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>
- 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>
+ 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>
+ <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 several native thread implementations, e.g.
- POSIX threads, win32 threads or Solaris threads.
- </para>
+ <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 --with-pcre=system option to configure,
- but it is not recommended.
- </para>
+ <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>
@@ -165,179 +161,112 @@ How to compile GLib itself
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>
- configure 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> configure option.
+ 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.
+ 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.
+ 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>
+ </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:
-
- <cmdsynopsis>
- <command>configure</command>
- <group>
- <arg>--enable-debug=[no|minimum|yes]</arg>
- </group>
- <group>
- <arg>--disable-gc-friendly</arg>
- <arg>--enable-gc-friendly</arg>
- </group>
- <group>
- <arg>--disable-mem-pools</arg>
- <arg>--enable-mem-pools</arg>
- </group>
- <group>
- <arg>--disable-threads</arg>
- <arg>--enable-threads</arg>
- </group>
- <group>
- <arg>--with-threads=[none|posix|dce|win32]</arg>
- </group>
- <group>
- <arg>--disable-regex</arg>
- <arg>--enable-regex</arg>
- </group>
- <group>
- <arg>--with-pcre=[internal|system]</arg>
- </group>
- <group>
- <arg>--disable-included-printf</arg>
- <arg>--enable-included-printf</arg>
- </group>
- <group>
- <arg>--disable-Bsymbolic</arg>
- <arg>--enable-Bsymbolic</arg>
- </group>
- <group>
- <arg>--disable-gtk-doc</arg>
- <arg>--enable-gtk-doc</arg>
- </group>
- <group>
- <arg>--disable-man</arg>
- <arg>--enable-man</arg>
- </group>
- <group>
- <arg>--disable-xattr</arg>
- <arg>--enable-xattr</arg>
- </group>
- <group>
- <arg>--disable-selinux</arg>
- <arg>--enable-selinux</arg>
- </group>
- <group>
- <arg>--disable-dtrace</arg>
- <arg>--enable-dtrace</arg>
- </group>
- <group>
- <arg>--disable-systemtap</arg>
- <arg>--enable-systemtap</arg>
- </group>
- <group>
- <arg>--enable-gcov</arg>
- <arg>--disable-gcov</arg>
- </group>
- <group>
- <arg>--with-runtime-libdir=RELPATH</arg>
- </group>
- </cmdsynopsis>
- </para>
+ <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>
+ <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>
+ <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>
+ <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>
- </formalpara>
+ <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>
- </para>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
@@ -345,10 +274,11 @@ How to compile GLib itself
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>
+ <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
@@ -359,284 +289,260 @@ How to compile GLib itself
and <function>g_free()</function> functions. Code currently affected by
this:
<itemizedlist>
- <listitem>
- <para>
- <structname>GList</structname>, <structname>GSList</structname>,
- <structname>GNode</structname>, <structname>GHash</structname>
- allocations. The functions g_list_push_allocator(),
- g_list_pop_allocator(), g_slist_push_allocator(),
- g_slist_pop_allocator(), g_node_push_allocator() and
- g_node_pop_allocator() are not available
- </para>
- </listitem>
- <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>
+ <listitem>
+ <para>
+ <structname>GList</structname>, <structname>GSList</structname>,
+ <structname>GNode</structname>, <structname>GHash</structname>
+ allocations. The functions g_list_push_allocator(),
+ g_list_pop_allocator(), g_slist_push_allocator(),
+ g_slist_pop_allocator(), g_node_push_allocator() and
+ g_node_pop_allocator() are not available
+ </para>
+ </listitem>
+ <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>--disable-threads</systemitem> and
- <systemitem>--enable-threads</systemitem></title>
-
- <para>
- Do not compile GLib to be multi thread safe. GLib
- will be slightly faster then. This is however not
- recommended, as many programs rely on GLib being
- multi thread safe.
- </para>
- </formalpara>
+ </formalpara>
- <formalpara>
- <title><systemitem>--with-threads</systemitem></title>
+ <formalpara>
+ <title><systemitem>--with-threads</systemitem></title>
- <para>
- Specify a thread implementation to use.
- <itemizedlist>
- <listitem><para>
- 'posix' and 'dce' can be used interchangeable
- to mean the different versions of Posix
- threads. configure tries to find out, which
- one is installed.
- </para></listitem>
-
- <listitem><para>
- 'none' means that GLib will be thread safe,
- but does not have a default thread
- implementation. This has to be supplied to
- <function>g_thread_init()</function> by the programmer.
- </para></listitem>
- </itemizedlist>
-
- </para>
- </formalpara>
+ <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>
+ <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>
+ <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>
+ <formalpara>
+ <title><systemitem>--with-pcre</systemitem></title>
- <para>
- Specify whether to use the internal or the system-supplied
- PCRE library.
- <itemizedlist>
- <listitem><para>
+ <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>
+ </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>
+ </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>
+ <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 <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.
- These options can be used to explicitly control whether
- an implementation fo the <function>printf()</function> family
- should be included or not.
- </para>
- </formalpara>
+ <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 fo the printf() family should be included or not.
+ </para>
+ </formalpara>
- <formalpara>
- <title><systemitem>--disable-Bsymbolic</systemitem> and
- <systemitem>--enable-Bsymbolic</systemitem></title>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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
+ 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>
- <para>
- By default the <command>configure</command> script will
- detect if DTrace support is available, and use it.
- </para>
- </formalpara>
+ <formalpara>
+ <title><systemitem>--disable-dtrace</systemitem> and
+ <systemitem>--enable-dtrace</systemitem></title>
- <formalpara>
- <title><systemitem>--disable-systemtap</systemitem> and
- <systemitem>--enable-systemtap</systemitem></title>
+ <para>
+ By default the <command>configure</command> script will
+ detect if DTrace support is available, and use it.
+ </para>
+ </formalpara>
- <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>--disable-systemtap</systemitem> and
+ <systemitem>--enable-systemtap</systemitem></title>
- <formalpara>
- <title><systemitem>--enable-gcov</systemitem> and
- <systemitem>--disable-gcov</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>
- <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>--enable-gcov</systemitem> and
+ <systemitem>--disable-gcov</systemitem></title>
- <formalpara>
- <title><systemitem>--with-runtime-libdir=RELPATH</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>
- <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-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>
- </refsect1>
+ </refsect1>
</refentry>
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index 8399115..3b394f1 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
@@ -17,17 +17,17 @@
<chapter id="glib">
<title>GLib Overview</title>
<para>
-GLib is a general-purpose utility library, which provides many useful data
-types, macros, type conversions, string utilities, file utilities, a main
-loop abstraction, and so on. It works on many UNIX-like platforms, Windows,
-OS/2 and BeOS. GLib is released under the GNU Library General Public License
-(GNU LGPL).
+ GLib is a general-purpose utility library, which provides many useful
+ data types, macros, type conversions, string utilities, file utilities,
+ a mainloop abstraction, and so on. It works on many UNIX-like platforms,
+ Windows, OS/2 and BeOS. GLib is released under the GNU Library General
+ Public License (GNU LGPL).
</para>
<para>
-The general policy of GLib is that all functions are invisibly threadsafe with the
-exception of data structure manipulation functions, where, if you have two threads
-manipulating the <emphasis>same</emphasis> data structure, they must use a lock to
-synchronize their operation.
+ The general policy of GLib is that all functions are invisibly threadsafe
+ with the exception of data structure manipulation functions, where, if
+ you have two threads manipulating the <emphasis>same</emphasis> data
+ structure, they must use a lock to synchronize their operation.
</para>
<xi:include href="building.sgml" />
@@ -60,6 +60,7 @@ synchronize their operation.
<xi:include href="xml/async_queues.xml" />
<xi:include href="xml/modules.xml" />
<xi:include href="xml/memory.xml" />
+ <xi:include href="xml/memory_slices.xml" />
<xi:include href="xml/iochannels.xml" />
<xi:include href="xml/error_reporting.xml" />
<xi:include href="xml/warnings.xml" />
@@ -68,69 +69,68 @@ synchronize their operation.
<chapter id="glib-utilities">
<title>GLib Utilities</title>
- <xi:include href="xml/string_utils.xml" />
- <xi:include href="xml/conversions.xml" />
- <xi:include href="xml/unicode.xml" />
- <xi:include href="xml/base64.xml" />
- <xi:include href="xml/checksum.xml" />
- <xi:include href="xml/hmac.xml" />
- <xi:include href="xml/i18n.xml" />
- <xi:include href="xml/date.xml" />
- <xi:include href="xml/timezone.xml" />
- <xi:include href="xml/date-time.xml" />
- <xi:include href="xml/random_numbers.xml" />
- <xi:include href="xml/hooks.xml" />
- <xi:include href="xml/misc_utils.xml" />
- <xi:include href="xml/scanner.xml" />
- <xi:include href="xml/timers.xml" />
- <xi:include href="xml/spawn.xml" />
- <xi:include href="xml/fileutils.xml" />
- <xi:include href="xml/gurifuncs.xml" />
- <xi:include href="xml/ghostutils.xml" />
- <xi:include href="xml/shell.xml" />
- <xi:include href="xml/option.xml" />
- <xi:include href="xml/patterns.xml" />
- <xi:include href="xml/gregex.xml" />
- <xi:include href="regex-syntax.sgml" />
- <xi:include href="xml/markup.xml" />
- <xi:include href="xml/keyfile.xml" />
- <xi:include href="xml/bookmarkfile.xml" />
- <xi:include href="xml/testing.xml" />
- <xi:include href="xml/gunix.xml" />
- <xi:include href="xml/windows.xml" />
+ <xi:include href="xml/string_utils.xml" />
+ <xi:include href="xml/conversions.xml" />
+ <xi:include href="xml/unicode.xml" />
+ <xi:include href="xml/base64.xml" />
+ <xi:include href="xml/checksum.xml" />
+ <xi:include href="xml/hmac.xml" />
+ <xi:include href="xml/i18n.xml" />
+ <xi:include href="xml/date.xml" />
+ <xi:include href="xml/timezone.xml" />
+ <xi:include href="xml/date-time.xml" />
+ <xi:include href="xml/random_numbers.xml" />
+ <xi:include href="xml/hooks.xml" />
+ <xi:include href="xml/misc_utils.xml" />
+ <xi:include href="xml/scanner.xml" />
+ <xi:include href="xml/timers.xml" />
+ <xi:include href="xml/spawn.xml" />
+ <xi:include href="xml/fileutils.xml" />
+ <xi:include href="xml/gurifuncs.xml" />
+ <xi:include href="xml/ghostutils.xml" />
+ <xi:include href="xml/shell.xml" />
+ <xi:include href="xml/option.xml" />
+ <xi:include href="xml/patterns.xml" />
+ <xi:include href="xml/gregex.xml" />
+ <xi:include href="regex-syntax.sgml" />
+ <xi:include href="xml/markup.xml" />
+ <xi:include href="xml/keyfile.xml" />
+ <xi:include href="xml/bookmarkfile.xml" />
+ <xi:include href="xml/testing.xml" />
+ <xi:include href="xml/gunix.xml" />
+ <xi:include href="xml/windows.xml" />
</chapter>
<chapter id="glib-data-types">
<title>GLib Data Types</title>
- <xi:include href="xml/memory_slices.xml" />
- <xi:include href="xml/linked_lists_double.xml" />
- <xi:include href="xml/linked_lists_single.xml" />
- <xi:include href="xml/queue.xml" />
- <xi:include href="xml/sequence.xml" />
- <xi:include href="xml/trash_stack.xml" />
- <xi:include href="xml/hash_tables.xml" />
- <xi:include href="xml/strings.xml" />
- <xi:include href="xml/string_chunks.xml" />
- <xi:include href="xml/arrays.xml" />
- <xi:include href="xml/arrays_pointer.xml" />
- <xi:include href="xml/arrays_byte.xml" />
- <xi:include href="xml/trees-binary.xml" />
- <xi:include href="xml/trees-nary.xml" />
- <xi:include href="xml/quarks.xml" />
- <xi:include href="xml/datalist.xml" />
- <xi:include href="xml/datasets.xml" />
- <xi:include href="xml/gvarianttype.xml"/>
- <xi:include href="xml/gvariant.xml"/>
- <xi:include href="gvariant-varargs.xml"/>
- <xi:include href="gvariant-text.xml"/>
+ <xi:include href="xml/linked_lists_double.xml" />
+ <xi:include href="xml/linked_lists_single.xml" />
+ <xi:include href="xml/queue.xml" />
+ <xi:include href="xml/sequence.xml" />
+ <xi:include href="xml/trash_stack.xml" />
+ <xi:include href="xml/hash_tables.xml" />
+ <xi:include href="xml/strings.xml" />
+ <xi:include href="xml/string_chunks.xml" />
+ <xi:include href="xml/arrays.xml" />
+ <xi:include href="xml/arrays_pointer.xml" />
+ <xi:include href="xml/arrays_byte.xml" />
+ <xi:include href="xml/trees-binary.xml" />
+ <xi:include href="xml/trees-nary.xml" />
+ <xi:include href="xml/quarks.xml" />
+ <xi:include href="xml/datalist.xml" />
+ <xi:include href="xml/datasets.xml" />
+ <xi:include href="xml/gvarianttype.xml"/>
+ <xi:include href="xml/gvariant.xml"/>
+ <xi:include href="gvariant-varargs.xml"/>
+ <xi:include href="gvariant-text.xml"/>
</chapter>
<chapter id="deprecated">
- <title>Deprecated APIs</title>
- <xi:include href="xml/threads-deprecated.xml"/>
- <xi:include href="xml/caches.xml" />
- <xi:include href="xml/relations.xml" />
- <xi:include href="xml/completion.xml" />
+ <title>Deprecated APIs</title>
+ <xi:include href="xml/threads-deprecated.xml"/>
+ <xi:include href="xml/caches.xml" />
+ <xi:include href="xml/relations.xml" />
+ <xi:include href="xml/completion.xml" />
</chapter>
<chapter id="tools">
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
