From dda319c7db30c4c11c7d39c998e2991f552383f1 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 28 Apr 2023 00:07:12 +0100 Subject: docs: Port docs/macros.txt to Markdown and update it Signed-off-by: Philip Withnall --- docs/macros.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/macros.txt | 56 ------------------------------------------- 2 files changed, 73 insertions(+), 56 deletions(-) create mode 100644 docs/macros.md delete mode 100644 docs/macros.txt diff --git a/docs/macros.md b/docs/macros.md new file mode 100644 index 000000000..eac9b6db9 --- /dev/null +++ b/docs/macros.md @@ -0,0 +1,73 @@ +GLib's configure options and corresponding macros +================================================= + +The following Meson configure options will result in certain macros or options +being defined at build time: + +`--buildtype={plain,release,minsize,custom}` + : No special macros or options +`--buildtype={debug,debugoptimized}` (`debugoptimized` is the default) + : `-DG_ENABLE_DEBUG -g` +`-Dglib_debug=disabled` + : Omits `G_ENABLE_DEBUG` when implied by `--buildtype`/`-Ddebug` +`-Dglib_debug=enabled` + : Defines `G_ENABLE_DEBUG` regardless of `--buildtype`/`-Ddebug` +`-Dglib_asserts=false` + : `-DG_DISABLE_ASSERT` +`-Dglib_checks=false` + : `-DG_DISABLE_CHECKS` + +Besides these, there are some local feature specific options, but the main +focus here is to concentrate on macros that affect overall GLib behaviour +and/or third party code. + + +GLib's internal and global macros +================================= + +`G_DISABLE_ASSERT` +--- + +The `g_assert()` and `g_assert_not_reached()` macros 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. Defining it when building GLib +will only disable the assertion macros for GLib itself, but third-party code +that passes `-DG_DISABLE_ASSERT` to the compiler in 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, as they may get compiled out. + +`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()`. + +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 when this +macro is defined, and since it is a globally visible define, third-party code +may be affected by it similarly to `G_DISABLE_ASSERT`. + +The additional code executed/compiled for this macro currently includes the +following, but this is not an exhaustive list: + - extra validity checks for `GDate` + - breakpoint abortion for fatal log levels in `gmessages.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 and type bookkeeping in `gobject.c` + - extra validity checks in `gsignal.c` + - support for tracking still-alive `GTask`s diff --git a/docs/macros.txt b/docs/macros.txt deleted file mode 100644 index 71a42db03..000000000 --- a/docs/macros.txt +++ /dev/null @@ -1,56 +0,0 @@ -GLib's configure options and corresponding macros -================================================= - ---buildtype={plain,release,minsize,custom} - none ---buildtype={debug,debugoptimized} [debugoptimized is the default] - -DG_ENABLE_DEBUG -g --Dglib_debug=disabled - Omits G_ENABLE_DEBUG when implied by --buildtype/-Ddebug --Dglib_debug=enabled - Defines G_ENABLE_DEBUG regardless of --buildtype/-Ddebug --Dglib_asserts=false - -DG_DISABLE_ASSERT --Dglib_checks=false - -DG_DISABLE_CHECKS - -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 -========================================== - -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. Defining it when building GLib - 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 - - 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 and type bookkeeping in gobject.c - - extra validity checks in gsignal.c \ No newline at end of file -- cgit v1.2.1