From cdcf0ac63f0df5312f81710b3bdf12a02cb1d4ee Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 17 Jan 2002 23:06:12 +0000 Subject: [PATCH] New files. * 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. --- docs/reference/ChangeLog | 10 ++ docs/reference/glib/Makefile.am | 8 +- docs/reference/glib/building.sgml | 217 +++++++++++++++++++++++++++ docs/reference/glib/changes-2.0.sgml | 142 ++++++++++++++++++ docs/reference/glib/compiling.sgml | 56 +++++++ docs/reference/glib/glib-docs.sgml | 52 ++++++- docs/reference/glib/resources.sgml | 111 ++++++++++++++ docs/reference/glib/running.sgml | 75 +++++++++ 8 files changed, 669 insertions(+), 2 deletions(-) create mode 100644 docs/reference/glib/building.sgml create mode 100644 docs/reference/glib/changes-2.0.sgml create mode 100644 docs/reference/glib/compiling.sgml create mode 100644 docs/reference/glib/resources.sgml create mode 100644 docs/reference/glib/running.sgml diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 666308df..78ee042e 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +2002-01-16 Matthias Clasen + + * 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 * glib/tmpl/threads.sgml: Name the right function. diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am index f0b4105a..fcce6f5b 100644 --- a/docs/reference/glib/Makefile.am +++ b/docs/reference/glib/Makefile.am @@ -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 = \ diff --git a/docs/reference/glib/building.sgml b/docs/reference/glib/building.sgml new file mode 100644 index 00000000..212d4b4e --- /dev/null +++ b/docs/reference/glib/building.sgml @@ -0,0 +1,217 @@ + + +Compiling the GLib package +3 +GLib Library + + + +Compiling the GLib Package + +How to compile GLib itself + + + + + Building the Library on UNIX + + On UNIX, GLib uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles + that comply with the GNU Coding Standards, and + libtool for building shared + libraries on multiple platforms. The normal sequence for + compiling and installing the GLib library is thus: + + + ./configure + make + make install + + + + + The standard options provided by GNU + autoconf may be passed to the + configure script. Please see the + autoconf documentation or run + ./configure --help for information about + the standard options. + + + + + Extra Configuration Options + + + In addition to the normal options, the + configure script in the GTK+ + library supports these additional arguments: + + + configure + + --enable-debug=[no|minimum|yes] + + + --disable-gc-friendly + --enable-gc-friendly + + + --disable-mem-pools + --enable-mem-pools + + + --disable-threads + --enable-threads + + + --with-threads=[none|posix|dce|solaris|win32] + + + --disable-gtk-doc + --enable-gtk-doc + + + + + + <systemitem>--enable-debug</systemitem> + + + 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 + runtime debugging. + 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 + should not + be used for stable releases of gtk+. + + + + + <systemitem>--disable-gc-friendly</systemitem> and + <systemitem>--enable-gc-friendly</systemitem> + + + 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. + + + + + <systemitem>--disable-mem-pools</systemitem> and + <systemitem>--enable-mem-pools</systemitem> + + + 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 g_malloc() + and g_free() functions. Code currently affected by + this: + + + + GList, GSList, + GNode allocations + + + + + GMemChunks become basically non-effective + + + + + GSignal disables all caching (potentially + very slow) + + + + + GType doesn't honour the + GTypeInfo + n_preallocs field anymore + + + + + the GBSearchArray flag + G_BSEARCH_ALIGN_POWER2 becomes non-functional + + + + + + + + <systemitem>--disable-threads</systemitem> and + <systemitem>--enable-threads</systemitem> + + + 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. + + + + + <systemitem>--with-threads</systemitem> + + + Specify a thread implementation to use. + + + 'posix' and 'dce' can be used interchangeable + to mean the different versions of posix + threads. configure tries to find out, which + one is installed. + + + + 'solaris' uses the native Solaris thread implementation. + + + + '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. + + + + + + + + <systemitem>--disable-gtk-doc</systemitem> and + <systemitem>--enable-gtk-doc</systemitem> + + + By default the configure script will try + to auto-detect whether the + gtk-doc 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 + gtk-doc 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. + + + + + + diff --git a/docs/reference/glib/changes-2.0.sgml b/docs/reference/glib/changes-2.0.sgml new file mode 100644 index 00000000..58aab546 --- /dev/null +++ b/docs/reference/glib/changes-2.0.sgml @@ -0,0 +1,142 @@ + + +Changes from 1.0 to 2.0 +3 +Changes from 1.0 to 2.0 + + + +Changes from 1.0 to 2.0 + +Incompatible changes made between version 1.0 and version 2.0 + + + + + +Incompatible changes from 1.0 to 2.0 + + +The GNOME 2.0 +porting guide on http://developer.gnome.org +has some more detailed discussion of porting from 1.0 to 2.0. +See the section on GLib. + + + + + + +The event loop functionality GMain has extensively +been revised to support multiple separate main loops in separate threads. +All sources (timeouts, idle functions, etc.) are associated with a +GMainContext. + + + +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. + + + +The main changes here are: + + + + + + Sources are now exposed as GSource *, rather than simply as + numeric ids. + + + + + + New types of sources are created by structure "derivation" from + GSource, so the source_data + parameter to the GSource virtual functions has been + replaced with a GSource *. + + + + + + Sources are first created, then later added to a specific + GMainContext. + + + + + + Dispatching has been modified so both the callback and data are passed + in to the dispatch() virtual function. + + + + + To go along with this change, the vtable for + GIOChannel has changed and + add_watch() has been replaced by + create_watch(). + + + + + +g_list_foreach() and +g_slist_foreach() have been changed so they +are now safe against removal of the current item, not the next item. + + + +It's not recommended to mutate the list in the callback to these +functions in any case. + + + + + +GDate 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 g_locale_to_utf8() first. + + + + + +g_strsplit() has been fixed to: + + + + + include trailing empty tokens, rather than stripping them + + + + + split into a maximum of max_tokens tokens, rather + than max_tokens + 1 + + + + + Code depending on either of these bugs will need to be fixed. + + + + + +Deprecated functions that got removed: +g_set_error_handler(), +g_set_warning_handler(), +g_set_message_handler(), use +g_log_set_handler() instead. + + + + + + + diff --git a/docs/reference/glib/compiling.sgml b/docs/reference/glib/compiling.sgml new file mode 100644 index 00000000..057b8ef6 --- /dev/null +++ b/docs/reference/glib/compiling.sgml @@ -0,0 +1,56 @@ + + +Compiling GLib Applications +3 +GLib Library + + + +Compiling GLib Applications + +How to compile your GLib application + + + + +Compiling GLib Applications on UNIX + + +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 +pkg-config utility. + + +The following interactive shell session demonstrates how +pkg-config is used: + +$ 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 + + + +If your application uses modules, threads or GObject +features, it must be compiled and linked with the options returned by the +following pkg-config invokations: + +$ pkg-config --cflags --libs gmodule-2.0 +$ pkg-config --cflags --libs gthread-2.0 +$ pkg-config --cflags --libs gobject-2.0 + + + +The simplest way to compile a program is to use the "backticks" +feature of the shell. If you enclose a command in backticks +(not single quotes), then its output will be +substituted into the command line before execution. So to compile +a GLib Hello, World, you would type the following: + +$ cc `pkg-config --cflags --libs glib-2.0` hello.c -o hello + + + + + + diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index 67df7d59..1e8dd2e0 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -52,12 +52,62 @@ + + + + + + ]> GLib Reference Manual + + GLib Overview + +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 depends on the following: + + + +iconv() + +In order to implement conversions between character sets, +GLib requires an implementation of the standard iconv() +routine. Most modern systems will have a suitable implementation, however +many older systems lack an iconv() implementation. On +such systems, you must install the +libiconv library. + + + + +a thread implementation + +The thread support in GLib can be based upon several native thread +implementations, e.g. POSIX threads, DCE threads or Solaris threads. + + + + + + + &glib-Building; + &glib-Compiling; + &glib-Running; + &glib-Changes-2-0; + &glib-Resources; + + + GLib Fundamentals &glib-Basic-Types; @@ -125,4 +175,4 @@ &glib-Caches; &glib-Memory-Allocators; - \ No newline at end of file + diff --git a/docs/reference/glib/resources.sgml b/docs/reference/glib/resources.sgml new file mode 100644 index 00000000..8d29eda1 --- /dev/null +++ b/docs/reference/glib/resources.sgml @@ -0,0 +1,111 @@ + + +Mailing lists and bug reports +3 +Mailing lists and bug reports + + + +Mailing lists and bug reports + +Getting help with GLib + + + + +Filing a bug report or feature request + + +If you encounter a bug, misfeature, or missing feature in GLib, please +file a bug report on +http://bugzilla.gnome.org. +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. + + + +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. + + + +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. + + + + + +Submitting Patches + + +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 diff utility, using the + 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. + + + +If you want to discuss your patch before or after developing it, mail +gtk-devel-list@gnome.org. +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. + + + + + +Mailing lists + + +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 +http://mail.gnome.org. + + + + + + +gtk-list@gnome.org + +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. + + + + +gtk-devel-list@gnome.org + +gtk-devel-list is for discussion of work on GTK+ (and GLib) itself, it is +not 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. + + + + +gtk-doc-list@gnome.org + +gtk-doc-list is for discussion of the gtk-doc +documentation system (used to document GTK+ and Glib), and for work on the GTK+ +(and GLib) documentation. + + + + + + + + + + diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml new file mode 100644 index 00000000..7e7e2958 --- /dev/null +++ b/docs/reference/glib/running.sgml @@ -0,0 +1,75 @@ + + +Running GLib Applications +3 +GLib Library + + + +Running GLib Applications + +How to run and debug your GLib application + + + + +Running and debugging GLib Applications + + +Environment variables + + +GLib inspects a few of environment variables in addition to standard +variables like LANG, PATH or HOME. + + + + <envar>G_BROKEN_FILENAMES<envar> + + + If this environment variable is set, GLib assumes that filenames are in + the locale encoding rather than in UTF-8. + + + + + <envar>G_MESSAGES_PREFIXED</envar> + + + 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. + + + + + + +Traps and traces + + +Some code portions contain trap variables that can be set during debugging +time if GLib has been configured with . +Such traps lead to immediate code halts to examine the current program state +and backtrace. + + + +Currently, the following trap variables exist: + +static volatile gulong g_trap_free_size; +static volatile gulong g_trap_realloc_size; +static volatile gulong g_trap_malloc_size; + +If set to a size > 0, g_free(), +g_realloc() and +g_malloc() will be intercepted if the size +matches the size of the corresponding memory block. This will only work with +g_mem_set_vtable (glib_mem_profiler_table) upon startup +though, because memory profiling is required to match on the memory block sizes. + + + + + + -- 2.34.1