docs/macros.txt

   1
   2
   3 GLib's configure options and corresponding macros
   4 =================================================
   5
   6 --enable-debug=no
   7         -DG_DISABLE_ASSERT -DG_DISABLE_CHECKS
   8 --enable-debug=minimum  [default for stable branches]
   9         none
  10 --enable-debug=yes      [default for development branches]
  11         -DG_ENABLE_DEBUG -g
  12 --enable-gc-friendly=yes
  13         #define ENABLE_GC_FRIENDLY 1
  14 --disable-mem-pools=yes
  15         #define DISABLE_MEM_POOLS 1
  16
  17 Besides these, there are some local feature specific options, but my main
  18 focus here is to concentrate on macros that affect overall GLib behaviour
  19 and/or third party code.
  20
  21
  22 Notes on GLib's internal and global macros
  23 ==========================================
  24
  25
  26 ENABLE_GC_FRIENDLY
  27         Newly allocated memory that isn't directly initialized, as well
  28         as memory being freed should be reset to 0. The point here is to
  29         allow memory checkers and similar programs that use bohem GC alike
  30         algorithms to produce more accurate results.
  31 DISABLE_MEM_POOLS
  32         Many small chunks of memory are often allocated via collective pools
  33         in GLib and are cached after release to speed up reallocations.
  34         For sparse memory systems this behaviour is often inferior, so
  35         memory pools can be disabled to avoid excessive caching and force
  36         atomic maintenance of chunks through the g_malloc/g_free.
  37         Code currently affected by this macro:
  38         - GList, GSList, GNode allocations
  39         - GMemChunks become basically non-effective
  40         - GSignal disables all caching (potentially very slow)
  41         - GType doesn't honour the GTypeInfo n_preallocs field anymore
  42         - the GBSearchArray flag G_BSEARCH_ALIGN_POWER2 becomes non-functional
  43 G_DISABLE_ASSERT
  44         The g_assert() and g_assert_not_reached() become non-functional
  45         with this define. The motivation is to speed up end-user apps by
  46         avoiding expensive checks.
  47         This macro can affect third-party code. --enable-debug=no will only
  48         disable the assertion macros for GLib itself, but third-party code
  49         that passes -DG_DISABLE_ASSERT to the compiler upon its own build
  50         will end up with the non-functional variants after including glib.h
  51         as well.
  52         NOTE: Code inside the assertion macros should not have side effects
  53         that affect the operation of the program.
  54 G_DISABLE_CHECKS
  55         This macro is similar to G_DISABLE_ASSERT, it affects third-party
  56         code as mentioned above and the NOTE about G_DISABLE_ASSERT applies
  57         too. The macros that become non-functional here are
  58         g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
  59         g_return_val_if_reached().
  60         Additionally the glib_mem_profiler_table and g_mem_profile() from
  61         gmem.h become non-functional if this macro is supplied.
  62         This macro also switches off certain checks in the GSignal code.
  63 G_ENABLE_DEBUG
  64         Quite a bit of additional debugging code is compiled into GLib for this
  65         macro, and since it is a globally visible define, third-party code may
  66         be affected by it similar to G_DISABLE_ASSERT.
  67         The additional code executed/compiled for this macro currently involve:
  68         - extra validity checks for GDate
  69         - memory profiling traps in gmem.c (consult debugging.txt for details)
  70         - BREAKPOINT abortion for fatal log levels in gmessage.c instead of
  71           plain abort() to allow debuggers trapping and overriding them
  72         - added verbosity of gscanner.c to catch deprecated code paths
  73         - added verbosity of gutils.c to catch deprecated code paths
  74         - object ref/unref traps (consult debugging.txt) and object bookkeeping
  75           in gobject.c
  76         - extra validity checks in gsignal.c
  77
  78
  79 2000/12/28      Tim Janik