luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-05-31 09:50:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

New files.

Browse Source 
* glib/building.sgml, glib/compiling.sgml,
        glib/running.sgml, glib/resources.sgml,
        glib/changes-2.0.sgml: New files.

        * glib/Makefile.am (content_files): Add new files.

        * glib/glib-docs.sgml: Add an Overview chapter.
This commit is contained in:
Matthias Clasen 2002-01-17 23:06:12 +00:00
parent a1ebb7048f
commit cdcf0ac63f
8 changed files with 669 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/reference/ChangeLog
View File

@ -1,3 +1,13 @@
2002-01-16 Matthias Clasen <matthiasc@poet.de>
* glib/building.sgml, glib/compiling.sgml,
glib/running.sgml, glib/resources.sgml,
glib/changes-2.0.sgml: New files.
* glib/Makefile.am (content_files): Add new files.
* glib/glib-docs.sgml: Add an Overview chapter.
2002-01-08 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
* glib/tmpl/threads.sgml: Name the right function.

8
docs/reference/glib/Makefile.am
View File

@ -44,7 +44,13 @@ HTML_IMAGES = \
mainloop-states.gif
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
content_files =
content_files = \
running.sgml \
building.sgml \
changes-2.0.sgml \
compiling.sgml \
resources.sgml
# Other files to distribute
extra_files = \

217
docs/reference/glib/building.sgml Normal file
View File

@ -0,0 +1,217 @@
<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>
</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>
</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 GTK+
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|solaris|win32]</arg>
</group>
<group>
<arg>--disable-gtk-doc</arg>
<arg>--enable-gtk-doc</arg>
</group>
</cmdsynopsis>
</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="GLIB-Debug-Options">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 gtk+.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-gc-friendly</systemitem> and
<systemitem>--enable-gc-friendly</systemitem></title>
<para>
When enabled all memory freed by the application,
but retained by GLib for performance reasons
is set to zero, thus making deployed garbage
collection or memory profiling tools detect
unlinked memory correctly. This will make GLib
slightly slower and is thus disabled by 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>GList</structname>, <structname>GSList</structname>,
<structname>GNode</structname> allocations
</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>
<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>
'solaris' uses the native Solaris thread implementation.
</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
g_thread_init() by the programmer.
</para></listitem>
</itemizedlist>
</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>
</refsect1>
</refentry>

142
docs/reference/glib/changes-2.0.sgml Normal file
View File

@ -0,0 +1,142 @@
<refentry id="glib-changes-2-0" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Changes from 1.0 to 2.0</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Changes from 1.0 to 2.0</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Changes from 1.0 to 2.0</refname>
<refpurpose>
Incompatible changes made between version 1.0 and version 2.0
</refpurpose>
</refnamediv>
<refsect1>
<title>Incompatible changes from 1.0 to 2.0</title>
<para>
The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
porting guide</ulink> on <ulink
url="http://developer.gnome.org">http://developer.gnome.org</ulink>
has some more detailed discussion of porting from 1.0 to 2.0.
See the section on GLib.
</para>
<itemizedlist>
<listitem>
<para>
The event loop functionality <structname>GMain</structname> has extensively
been revised to support multiple separate main loops in separate threads.
All sources (timeouts, idle functions, etc.) are associated with a
<structname>GMainContext</structname>.
</para>
<para>
Compatibility functions exist so that most application code dealing with
the main loop will continue to work. However, code that creates new custom
types of sources will require modification.
</para>
<para>
The main changes here are:
<itemizedlist>
<listitem>
<para>
Sources are now exposed as <type>GSource *</type>, rather than simply as
numeric ids.
</para>
</listitem>
<listitem>
<para>
New types of sources are created by structure "derivation" from
<structname>GSource</structname>, so the <literal>source_data</literal>
parameter to the <structname>GSource</structname> virtual functions has been
replaced with a <type>GSource *</type>.
</para>
</listitem>
<listitem>
<para>
Sources are first created, then later added to a specific
<structname>GMainContext</structname>.
</para>
</listitem>
<listitem>
<para>
Dispatching has been modified so both the callback and data are passed
in to the <function>dispatch()</function> virtual function.
</para>
</listitem>
</itemizedlist>
To go along with this change, the vtable for
<structname>GIOChannel</structname> has changed and
<function>add_watch()</function> has been replaced by
<function>create_watch()</function>.
</para>
</listitem>
<listitem>
<para>
<function>g_list_foreach()</function> and
<function>g_slist_foreach()</function> have been changed so they
are now safe against removal of the current item, not the next item.
</para>
<para>
It's not recommended to mutate the list in the callback to these
functions in any case.
</para>
</listitem>
<listitem>
<para>
<structname>GDate</structname> now works in UTF-8, not in the current locale.
If you want to use it with the encoding of the locale, you need to convert
strings using <function>g_locale_to_utf8()</function> first.
</para>
</listitem>
<listitem>
<para>
<function>g_strsplit()</function> has been fixed to:
<itemizedlist>
<listitem>
<para>
include trailing empty tokens, rather than stripping them
</para>
</listitem>
<listitem>
<para>
split into a maximum of <literal>max_tokens</literal> tokens, rather
than <literal>max_tokens + 1</literal>
</para>
</listitem>
</itemizedlist>
Code depending on either of these bugs will need to be fixed.
</para>
</listitem>
<listitem>
<para>
Deprecated functions that got removed:
<function>g_set_error_handler()</function>,
<function>g_set_warning_handler()</function>,
<function>g_set_message_handler()</function>, use
<function>g_log_set_handler()</function> instead.
</para>
</listitem>
<itemizedlist>
</refsect1>
</refentry>

56
docs/reference/glib/compiling.sgml Normal file
View File

@ -0,0 +1,56 @@
<refentry id="glib-compiling" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Compiling GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling GLib Applications</refname>
<refpurpose>
How to compile your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling GLib Applications on UNIX</title>
<para>
To compile a GLib application, you need to tell the compiler where to
find the GLib header files and libraries. This is done with the
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used:
<programlisting>
$ pkg-config --cflags glib-2.0
-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
$ pkg-config --libs glib-2.0
-L/usr/lib -lm -lglib-1.3
</programlisting>
</para>
<para>
If your application uses modules, threads or <structname>GObject</structname>
features, it must be compiled and linked with the options returned by the
following <application>pkg-config</application> invokations:
<programlisting>
$ pkg-config --cflags --libs gmodule-2.0
$ pkg-config --cflags --libs gthread-2.0
$ pkg-config --cflags --libs gobject-2.0
</programlisting>
</para>
<para>
The simplest way to compile a program is to use the "backticks"
feature of the shell. If you enclose a command in backticks
(<emphasis>not single quotes</emphasis>), then its output will be
substituted into the command line before execution. So to compile
a GLib Hello, World, you would type the following:
<programlisting>
$ cc `pkg-config --cflags --libs glib-2.0` hello.c -o hello
</programlisting>
</para>
</refsect1>
</refentry>

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

@ -52,12 +52,62 @@
<!entity glib-Shell SYSTEM "sgml/shell.sgml">
<!entity glib-Markup SYSTEM "sgml/markup.sgml">
<!entity glib-Compiling SYSTEM "compiling.sgml">
<!entity glib-Building SYSTEM "building.sgml">
<!entity glib-Running SYSTEM "running.sgml">
<!entity glib-Resources SYSTEM "resources.sgml">
<!entity glib-Changes-2-0 SYSTEM "changes-2.0.sgml">
]>
<book id="index">
<bookinfo>
<title>GLib Reference Manual</title>
</bookinfo>
<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).
</para>
<para>
GLib depends on the following:
<variablelist>
<varlistentry>
<term><function>iconv()</function></term>
<listitem><para>
In order to implement conversions between character sets,
GLib requires an implementation of the standard <function>iconv()</function>
routine. Most modern systems will have a suitable implementation, however
many older systems lack an <function>iconv()</function> implementation. On
such systems, you must install the
<ulink url="http://clisp.cons.org/~haible/packages-libiconv.html">libiconv</ulink> library.
</para></listitem>
</varlistentry>
<varlistentry>
<term>a thread implementation</term>
<listitem><para>
The thread support in GLib can be based upon several native thread
implementations, e.g. POSIX threads, DCE threads or Solaris threads.
</para></listitem>
</varlistentry>
</variablelist>
</para>
&glib-Building;
&glib-Compiling;
&glib-Running;
&glib-Changes-2-0;
&glib-Resources;
</chapter>
<chapter id="glib-fundamentals">
<title>GLib Fundamentals</title>
&glib-Basic-Types;
@ -125,4 +175,4 @@
&glib-Caches;
&glib-Memory-Allocators;
</chapter>
</book>
</book>

111
docs/reference/glib/resources.sgml Normal file
View File

@ -0,0 +1,111 @@
<refentry id="glib-resources" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Mailing lists and bug reports</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Mailing lists and bug reports</refname>
<refpurpose>
Getting help with GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Filing a bug report or feature request</title>
<para>
If you encounter a bug, misfeature, or missing feature in GLib, please
file a bug report on
<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.
We'd also appreciate reports of incomplete or misleading information in
the GLib documentation; file those against the "docs" component of the "glib"
product in Bugzilla.
</para>
<para>
Don't hesitate to file a bug report, even if you think we may know
about it already, or aren't sure of the details. Just give us as much
information as you have, and if it's already fixed or has already been
discussed, we'll add a note to that effect in the report.
</para>
<para>
The bug tracker should definitely be used for feature requests, it's
not only for bugs. We track all GLib development in Bugzilla, so it's
the way to be sure the GLib developers won't forget about an issue.
</para>
</refsect1>
<refsect1>
<title>Submitting Patches</title>
<para>
If you develop a bugfix or enhancement for GLib, please file that in
Bugzilla as well. Bugzilla allows you to attach files; please attach a
patch generated by the <command>diff</command> utility, using the
<option>-u</option> option to make the patch more readable. All patches
must be offered under the terms of the GNU LGPL license, so be sure you
are authorized to give us the patch under those terms.
</para>
<para>
If you want to discuss your patch before or after developing it, mail
<ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink>.
But be sure to file the Bugzilla report as well; if the patch is only on the
list and not in Bugzilla, it's likely to slip through the cracks.
</para>
</refsect1>
<refsect1>
<title>Mailing lists</title>
<para>
There are several mailing lists dedicated to GTK+ and related
libraries. Discussion of GLib generally takes place on these lists.
You can subscribe or view the archives of these lists on
<ulink url="http://mail.gnome.org">http://mail.gnome.org</ulink>.
</para>
<para>
<variablelist>
<varlistentry>
<term><ulink url="mailto:gtk-list@gnome.org">gtk-list@gnome.org</ulink></term>
<listitem><para>
gtk-list covers general GTK+ (and GLib) topics; questions about using GLib
in programs, GLib from a user standpoint, announcements of GLib-related projects
would all be on-topic. The bulk of the traffic consists of GTK+ programming
questions.
</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-devel-list@gnome.org">gtk-devel-list@gnome.org</ulink></term>
<listitem><para>
gtk-devel-list is for discussion of work on GTK+ (and GLib) itself, it is
<emphasis>not</emphasis> for asking questions about how to use GTK+ (or GLib)
in applications. gtk-devel-list is appropriate for discussion of patches,
bugs, proposed features, and so on.
</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="mailto:gtk-doc-list@gnome.org">gtk-doc-list@gnome.org</ulink></term>
<listitem><para>
gtk-doc-list is for discussion of the <application>gtk-doc</application>
documentation system (used to document GTK+ and Glib), and for work on the GTK+
(and GLib) documentation.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

75
docs/reference/glib/running.sgml Normal file
View File

@ -0,0 +1,75 @@
<refentry id="glib-running" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Running GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Running GLib Applications</refname>
<refpurpose>
How to run and debug your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Running and debugging GLib Applications</title>
<refsect2>
<title>Environment variables</title>
<para>
GLib inspects a few of environment variables in addition to standard
variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
</para>
<formalpara>
<title><envar>G_BROKEN_FILENAMES<envar></title>
<para>
If this environment variable is set, GLib assumes that filenames are in
the locale encoding rather than in UTF-8.
</para>
</formalpara>
<formalpara>
<title><envar>G_MESSAGES_PREFIXED</envar></title>
<para>
A list of log levels for which messages should be prefixed by the
program name and PID of the application. The default is to prefix
everything except %G_LOG_LEVEL_MESSAGE and %G_LOG_LEVEL_INFO.
</para>
</formalpara>
</refsect2>
<refsect2>
<title>Traps and traces</title>
<para>
Some code portions contain trap variables that can be set during debugging
time if GLib has been configured with <option>--enable-debug=yes</option>.
Such traps lead to immediate code halts to examine the current program state
and backtrace.
</para>
<para>
Currently, the following trap variables exist:
<programlisting>
static volatile gulong g_trap_free_size;
static volatile gulong g_trap_realloc_size;
static volatile gulong g_trap_malloc_size;
</programlisting>
If set to a size > 0, <link linkend="g-free">g_free()</link>,
<link linkend="g-realloc">g_realloc()</link> and
<link linkend="g-malloc">g_malloc()</link> will be intercepted if the size
matches the size of the corresponding memory block. This will only work with
<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup
though, because memory profiling is required to match on the memory block sizes.
</para>
</refsect2>
</refsect1>
</refentry>