+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.
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 = \
--- /dev/null
+<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>
--- /dev/null
+<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>
--- /dev/null
+<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>
<!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;
&glib-Caches;
&glib-Memory-Allocators;
</chapter>
-</book>
\ No newline at end of file
+</book>
--- /dev/null
+<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>
--- /dev/null
+<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>
projects / platform / upstream / glib.git / commitdiff