luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 05:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Some more docs reshuffling

Browse Source
This commit is contained in:
Matthias Clasen 2011-11-12 22:52:24 -05:00
parent 06bb6c75a2
commit e60846dc78
2 changed files with 517 additions and 611 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
docs/reference/glib/building.sgml
View File

@ -2,18 +2,16 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]> ]>
<refentry id="glib-building" revision="16 Jan 2002"> <refentry id="glib-building">
<refmeta> <refmeta>
<refentrytitle>Compiling the GLib package</refentrytitle> <refentrytitle>Compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum> <manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo> <refmiscinfo>GLib Library</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname>Compiling the GLib Package</refname> <refname>Compiling the GLib Package</refname>
<refpurpose> <refpurpose>How to compile GLib itself</refpurpose>
How to compile GLib itself
</refpurpose>
</refnamediv> </refnamediv>
<refsect1 id="building"> <refsect1 id="building">
@ -62,8 +60,7 @@ How to compile GLib itself
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<ulink <ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
is a tool for tracking the compilation flags needed for is a tool for tracking the compilation flags needed for
libraries that are used by the GLib library. (For each libraries that are used by the GLib library. (For each
library, a small <literal>.pc</literal> text file is library, a small <literal>.pc</literal> text file is
@ -145,8 +142,7 @@ How to compile GLib itself
<listitem> <listitem>
<para> <para>
A thread implementation is needed. The thread support in GLib A thread implementation is needed. The thread support in GLib
can be based upon several native thread implementations, e.g. can be based upon POSIX threads or win32 threads.
POSIX threads, win32 threads or Solaris threads.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -155,8 +151,8 @@ How to compile GLib itself
for regular expression matching. The default is to use the internal for regular expression matching. The default is to use the internal
version of PCRE that is patched to use GLib for memory management version of PCRE that is patched to use GLib for memory management
and Unicode handling. If you prefer to use the system-supplied PCRE and Unicode handling. If you prefer to use the system-supplied PCRE
library you can pass the --with-pcre=system option to configure, library you can pass the <option>--with-pcre=system</option> option
but it is not recommended. to, but it is not recommended.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -165,29 +161,32 @@ How to compile GLib itself
getxattr() family of functions that may be provided by glibc or getxattr() family of functions that may be provided by glibc or
by the standalone libattr library. To build GLib without extended by the standalone libattr library. To build GLib without extended
attribute support, use the <option>--disable-xattr</option> 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. configure option.
</para> </para>
</listitem> </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.
</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> </itemizedlist>
</refsect1> </refsect1>
@ -198,74 +197,6 @@ How to compile GLib itself
In addition to the normal options, the In addition to the normal options, the
<command>configure</command> script in the GLib <command>configure</command> script in the GLib
library supports these additional arguments: 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>
<formalpara> <formalpara>
@ -291,34 +222,31 @@ How to compile GLib itself
<para> <para>
By default, and with <systemitem>--disable-gc-friendly</systemitem> By default, and with <systemitem>--disable-gc-friendly</systemitem>
as well, Glib does not clear the memory for certain objects before they as well, Glib does not clear the memory for certain objects before
are freed. For example, Glib may decide to recycle GList nodes by they are freed. For example, Glib may decide to recycle GList nodes
putting them in a free list. However, memory profiling and debugging tools like <ulink by putting them in a free list. However, memory profiling and debugging
url="http://www.valgrind.org">Valgrind</ulink> work better if an tools like <ulink url="http://www.valgrind.org">Valgrind</ulink> work
application does not keep dangling pointers to freed memory (even better if an application does not keep dangling pointers to freed
though these pointers are no longer dereferenced), or invalid pointers inside memory (even though these pointers are no longer dereferenced), or
uninitialized memory. The invalid pointers inside uninitialized memory.
<systemitem>--enable-gc-friendly</systemitem> option makes Glib clear The <systemitem>--enable-gc-friendly</systemitem> option makes Glib
memory in these situations: clear memory in these situations:
</para> </para>
</formalpara>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
When shrinking a GArray, Glib will clear the memory no longer When shrinking a GArray, Glib will clear the memory no longer
available in the array: shrink an array from 10 bytes to 7, and 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. the last 3 bytes will be cleared. This includes removals of single
</para> and multiple elements.
</listitem>
<listitem>
<para>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
When growing a GArray, Glib will clear the new chunk of memory. 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. Grow an array from 7 bytes to 10 bytes, and the last 3 bytes will
be cleared.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -336,7 +264,8 @@ How to compile GLib itself
<listitem> <listitem>
<para> <para>
When destroying or removing a GTree node, Glib will clear the node, 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. which used to have pointers to the node's value, and the left and
right subnodes.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -345,6 +274,7 @@ How to compile GLib itself
Since clearing the memory has a cost, Since clearing the memory has a cost,
<systemitem>--disable-gc-friendly</systemitem> is the default. <systemitem>--disable-gc-friendly</systemitem> is the default.
</para> </para>
</formalpara>
<formalpara> <formalpara>
<title><systemitem>--disable-mem-pools</systemitem> and <title><systemitem>--disable-mem-pools</systemitem> and
@ -376,8 +306,8 @@ How to compile GLib itself
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<structname>GSignal</structname> disables all caching (potentially <structname>GSignal</structname> disables all caching
very slow) (potentially very slow)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -397,39 +327,13 @@ How to compile GLib itself
</para> </para>
</formalpara> </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> <title><systemitem>--with-threads</systemitem></title>
<para> <para>
Specify a thread implementation to use. Specify a thread implementation to use. Available options are
<itemizedlist> 'posix' or 'win32'. Normally, <command>configure</command>
<listitem><para> should be able to work out the system threads API on its own.
'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> </para>
</formalpara> </formalpara>
@ -452,15 +356,18 @@ How to compile GLib itself
Specify whether to use the internal or the system-supplied Specify whether to use the internal or the system-supplied
PCRE library. PCRE library.
<itemizedlist> <itemizedlist>
<listitem><para> <listitem>
<para>
'internal' means that GRegex will be compiled to use 'internal' means that GRegex will be compiled to use
the internal PCRE library. the internal PCRE library.
</para></listitem> </para>
</listitem>
<listitem><para> <listitem>
<para>
'system' means that GRegex will be compiled to use 'system' means that GRegex will be compiled to use
the system-supplied PCRE library. the system-supplied PCRE library.
</para></listitem> </para>
</listitem>
</itemizedlist> </itemizedlist>
Using the internal PCRE is the preferred solution: Using the internal PCRE is the preferred solution:
<itemizedlist> <itemizedlist>
@ -495,16 +402,15 @@ How to compile GLib itself
<para> <para>
By default the <command>configure</command> script will try By default the <command>configure</command> script will try
to auto-detect whether the C library provides a suitable set to auto-detect whether the C library provides a suitable set
of <function>printf()</function> functions. In detail, of printf() functions. In detail, <command>configure</command>
<command>configure</command> checks that the semantics of checks that the semantics of snprintf() are as specified by C99
<function>snprintf()</function> are as specified by C99 and and that positional parameters as specified in the Single Unix
that positional parameters as specified in the Single Unix
Specification are supported. If this not the case, GLib will Specification are supported. If this not the case, GLib will
include an implementation of the <function>printf()</function> include an implementation of the printf() family.
family. </para>
<para>
These options can be used to explicitly control whether These options can be used to explicitly control whether
an implementation fo the <function>printf()</function> family an implementation fo the printf() family should be included or not.
should be included or not.
</para> </para>
</formalpara> </formalpara>
@ -531,8 +437,8 @@ How to compile GLib itself
<para> <para>
By default the <command>configure</command> script will try By default the <command>configure</command> script will try
to auto-detect whether the to auto-detect whether the
<application>gtk-doc</application> package is installed. If <application>gtk-doc</application> package is installed.
it is, then it will use it to extract and build the If it is, then it will use it to extract and build the
documentation for the GLib library. These options documentation for the GLib library. These options
can be used to explicitly control whether can be used to explicitly control whether
<application>gtk-doc</application> should be <application>gtk-doc</application> should be
@ -549,8 +455,8 @@ How to compile GLib itself
<para> <para>
By default the <command>configure</command> script will try By default the <command>configure</command> script will try
to auto-detect whether <application>xsltproc</application> to auto-detect whether <application>xsltproc</application>
and the necessary Docbook stylesheets are installed. If and the necessary Docbook stylesheets are installed.
they are, then it will use them to rebuild the included If they are, then it will use them to rebuild the included
man pages from the XML sources. These options can be used man pages from the XML sources. These options can be used
to explicitly control whether man pages should be rebuilt to explicitly control whether man pages should be rebuilt
used or not. The distribution includes pre-generated man used or not. The distribution includes pre-generated man

20
docs/reference/glib/glib-docs.sgml
View File

@ -17,17 +17,17 @@
<chapter id="glib"> <chapter id="glib">
<title>GLib Overview</title> <title>GLib Overview</title>
<para> <para>
GLib is a general-purpose utility library, which provides many useful data GLib is a general-purpose utility library, which provides many useful
types, macros, type conversions, string utilities, file utilities, a main data types, macros, type conversions, string utilities, file utilities,
loop abstraction, and so on. It works on many UNIX-like platforms, Windows, a mainloop abstraction, and so on. It works on many UNIX-like platforms,
OS/2 and BeOS. GLib is released under the GNU Library General Public License Windows, OS/2 and BeOS. GLib is released under the GNU Library General
(GNU LGPL). Public License (GNU LGPL).
</para> </para>
<para> <para>
The general policy of GLib is that all functions are invisibly threadsafe with the The general policy of GLib is that all functions are invisibly threadsafe
exception of data structure manipulation functions, where, if you have two threads with the exception of data structure manipulation functions, where, if
manipulating the <emphasis>same</emphasis> data structure, they must use a lock to you have two threads manipulating the <emphasis>same</emphasis> data
synchronize their operation. structure, they must use a lock to synchronize their operation.
</para> </para>
<xi:include href="building.sgml" /> <xi:include href="building.sgml" />
@ -60,6 +60,7 @@ synchronize their operation.
<xi:include href="xml/async_queues.xml" /> <xi:include href="xml/async_queues.xml" />
<xi:include href="xml/modules.xml" /> <xi:include href="xml/modules.xml" />
<xi:include href="xml/memory.xml" /> <xi:include href="xml/memory.xml" />
<xi:include href="xml/memory_slices.xml" />
<xi:include href="xml/iochannels.xml" /> <xi:include href="xml/iochannels.xml" />
<xi:include href="xml/error_reporting.xml" /> <xi:include href="xml/error_reporting.xml" />
<xi:include href="xml/warnings.xml" /> <xi:include href="xml/warnings.xml" />
@ -102,7 +103,6 @@ synchronize their operation.
<chapter id="glib-data-types"> <chapter id="glib-data-types">
<title>GLib Data Types</title> <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_double.xml" />
<xi:include href="xml/linked_lists_single.xml" /> <xi:include href="xml/linked_lists_single.xml" />
<xi:include href="xml/queue.xml" /> <xi:include href="xml/queue.xml" />