1 files changed, 73 insertions, 0 deletions
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