docs/macros.txt and glib configuration

[Tim Janik <timj gtk org>]

hi all,

glib has quite a few configure time switches at this point (though
i just got rid of --enable-mem-check and --enable-mem-profile), so
i took the time to summarize them in docs/macros.txt (i actually
had to do this to make may way through the #ifdef jungle in the
old gmem.c).
quite some of them tweak inline functions or macros in the header
files and are thus third-party configurable for code that uses
glib header files though isn't glib itself (e.g. using g_assert()
in gtk or an application).

i'm not sure this is overly clever, for one, all glib-dependant code
has to carry on configure.in options from glib to keep those macros/
inline functions configurable, and for another, most of them only make
sense on a per-system basis (e.g. disabling checks/assertments or,
as alex plans it, disabling logging facilities to save memory) and
should be carried on to dependant libraries and apps.

a valid scenario though is to use a standard distribution package of
a stable branch glib, compiled without G_ENABLE_DEBUG, but to use
G_ENABLE_DEBUG features when developing an application against it,
so glib configuration shouldn't blindly dictate features for dependant
code.

a possible solution to this is to fixate glib configure.in time options
in glibconfig.h so they apply to dependant code unless explicitely overriden.
that might look like:

glibconfig.h:
#if !defined (G_DISABLE_DEBUG) && !defined (G_ENABLE_DEBUG)
#  define G_ENABLE_DEBUG  /* or G_DISABLE_DEBUG, depending on glib config */
#endif

the macros currently in question are: G_DISABLE_ASSERT, G_DISABLE_CHECKS,
and G_ENABLE_DEBUG which will gain corresponding G_ENABLE_ASSERT,
G_ENABLE_CHECKS and G_DISABLE_DEBUG companions with a scheme like the above.

also, ENABLE_GC_FRIENDLY and DISABLE_MEM_POOLS are probably good candidates
for G_* globalization, so third-party code can honour those settings if
it wants to.

as a side note, gtype.h also supports G_DISABLE_CAST_CHECKS to disable
object casts checking macros, this option is not yet configurable per
configure.in switch but probably should, similar to G_DISABLE_CHECKS.

i've appended the current contents of docs/macros.txt to give readers
a better idea of what exactly those macros are about (and yes, future
configure.in options/macros should be reflected in updates to this
file).

---
ciaoTJ



GLib's configure options and corresponding macros
=================================================

--enable-debug=no
	-DG_DISABLE_ASSERT -DG_DISABLE_CHECKS
--enable-debug=minimum	[default for stable branches]
	none
--enable-debug=yes	[default for development branches]
	-DG_ENABLE_DEBUG -g
--enable-gc-friendly=yes
	#define ENABLE_GC_FRIENDLY 1
--disable-mem-pools=yes
	#define DISABLE_MEM_POOLS 1

Besides these, there are some local feature specific options, but my main
focus here is to concentrate on macros that affect overall GLib behaviour
and/or third party code.


Notes on GLib's internal and global macros
==========================================


ENABLE_GC_FRIENDLY
	Newly allocated memory that isn't directly initialized, as well
	as memory being freed should be reset to 0. The point here is to
	allow memory checkers and similar programs that use bohem GC alike
	algorithms to produce more accurate results.
DISABLE_MEM_POOLS
	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/g_free.
	Code currently affected by this macro:
	- 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
G_DISABLE_ASSERT
	The g_assert() and g_assert_not_reached() become non-functional
	with this define. The motivation is to speed up end-user apps by
	avoiding expensive checks.
	This macro can affect third-party code. --enable-debug=no will only
	disable the assertion macros for GLib itself, but third-party code
	that passes -DG_DISABLE_ASSERT to the compiler upon its own build
	will end up with the non-functional variants after including glib.h
	as well.
	NOTE: Code inside the assertion macros should not have side effects
	that affect the operation of the program.
G_DISABLE_CHECKS
	This macro is similar to G_DISABLE_ASSERT, it affects third-party
	code as mentioned above and the NOTE about G_DISABLE_ASSERT applies
	too. The macros that become non-functional here are
	g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
	g_return_val_if_reached().
	Additionally the glib_mem_profiler_table and g_mem_profile() from
	gmem.h become non-functional if this macro is supplied.
	This macro also switches off certain checks in the GSignal code.
G_ENABLE_DEBUG
	Quite a bit of additional debugging code is compiled into GLib for this
	macro, and since it is a globally visible define, third-party code may
	be affected by it similar to G_DISABLE_ASSERT.
	The additional code executed/compiled for this macro currently involve:
	- extra validity checks for GDate
	- memory profiling traps in gmem.c (consult debugging.txt for details)
	- BREAKPOINT abortion for fatal log levels in gmessage.c instead of
	  plain abort() to allow debuggers trapping and overriding them
	- added verbosity of gscanner.c to catch deprecated code paths
	- added verbosity of gutils.c to catch deprecated code paths
	- object ref/unref traps (consult debugging.txt) and object bookkeeping
	  in gobject.c
	- extra validity checks in gsignal.c


2000/12/28	Tim Janik