luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-12 21:36:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Port docs/macros.txt to Markdown and update it

Browse Source 
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2023-04-28 00:07:12 +01:00
parent dc95b911f3
commit dda319c7db
2 changed files with 73 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/macros.md Normal file
View File

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

56
docs/macros.txt
View File

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