Re: docs/macros.txt and glib configuration

[Owen Taylor <otaylor redhat com>]

Tim Janik <timj gtk org> writes:

> 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).

Should the description of the configure be in macros.txt or in INSTALL?

> 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).

ENABLE_GC_FRIENDLY, DISABLE_MEM_POOLS, and G_ENABLE_DEBUG are not public,
and do not effect the header files. This is why the first two can
not have G_ prefixing.
 
> 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 

Disabling checks and assertions on a per-library basis is definitely
useful. Especially G_DISABLE_CHECKS. The reason why G_DISABLE_CHECKS
needs to be given explicitely to turn off checks was specifically
so that we could, by default, have checks turned off for GTK+ 
(unless --enable-debug is specified) and turned on by default for
client code.

> 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.

Yes.
 
> 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

This would be a bad idea. Whether you want to debug client code is
basically independnet of whether you want to debug libraries.
 
> 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.

I think it would be very confusing to have to specify G_ENABLE_CHECKS
or G_DISABLE_CHECKS differently depending on how GLib was compiled.
 
> 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.

We probably should have standard G_ prefixed names for these options, 
so you can do "export CPPFLAGS="-G_ENABLE_GC_FRIENDLY" in your ~/.profile,
but I don't think propagating global defaults through glibconfig.h
is appropriate.
 
> 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).
>
> 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

I'm pretty sure that --disable-mem-pools=yes, if it works at all,
is a synonym for --enable-mem-pools=yes.

Remember:

 --disable-mem-pools  ==  --enable-mem-pools=no

> 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
> ==========================================
 
Should these really be documented together? In fact, the public ones - 
the ones that effect header files - need to be documented in the
SGML reference documentation.
 
> 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

 'Boehm GC'  (Capitalize, and spelling)

> 	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

 s/sparse memory systems/low memory systems/.

> 	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.

(Which is a somewhat silly reuse of the macro)

> 	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

Isn't going into this level of detail just going to result in
this documentation become incorrect quickly?

Regards,
                                        Owen