doc/logflags.txt

   1 HEAD~ Log Flags; logflags; define hierarchies for logging output
   2
   3 Flags are used to inform NoBug about subsystems/modules or even finer
   4 grained sections of the code. These are referred to as 'channels' in other
   5 logging libraries.
   6
   7 A flag should be declared in a headerfile using the following mechanism:
   8
   9 INDEX DECLARE_FLAG; DECLARE_FLAG; declaring a flag
  10  NOBUG_DECLARE_FLAG(flagname)
  11
  12 It is advisable to do so in one of your header files.
  13
  14 Furthermore, the flag must be defined in some implementation file by using one
  15 of the following schemes:
  16
  17 INDEX DEFINE_FLAG; DEFINE_FLAG; defining a flag
  18  NOBUG_DEFINE_FLAG(flagname)
  19
  20 or:
  21
  22 INDEX DEFINE_FLAG_LIMIT; DEFINE_FLAG_LIMIT; defining a flag w/ log limit
  23  NOBUG_DEFINE_FLAG_LIMIT(flagname, limit)
  24
  25 Moreover, macros are available that accept a 'parent' flag as a parameter, which is then
  26 used to initialize the defaults from another flag:
  27
  28 INDEX DEFINE_FLAG_PARENT; DEFINE_FLAG_PARENT; defining a flag hierarchy
  29  NOBUG_DEFINE_FLAG_PARENT(flagname, parent)
  30
  31 or
  32
  33 INDEX DEFINE_FLAG_PARENT_LIMIT; DEFINE_FLAG_PARENT_LIMIT; defining a flag hierarchy, w/ log limit
  34  NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)
  35
  36 This can be used to create hierachies of flags
  37
  38
  39 PARA C++ support, C++ logflags; Cplusplus_logflags; C++ support for log flags
  40
  41 Additional macros are available for applications written in C++:
  42
  43  NOBUG_CPP_DEFINE_FLAG(name)
  44  NOBUG_CPP_DEFINE_FLAG_PARENT(name, parent)
  45  NOBUG_CPP_DEFINE_FLAG_LIMIT(name, default)
  46  NOBUG_CPP_DEFINE_FLAG_PARENT_LIMIT(name, parent, default)
  47
  48 These macros statically initialize the flags when they are defined, there is no
  49 need to call `NOBUG_INIT_FLAG()` (see below).
  50
  51
  52 .Force declarations only
  53
  54 When the the following preprocessor constant is defined to be `1`:
  55
  56 INDEX DECLARE_ONLY; DECLARE_ONLY; force flag declarations only
  57  NOBUG_DECLARE_ONLY
  58
  59 then *all* definitions here (`NOBUG_DEFINE_*`)
  60 become declarations only.  When this is defined to be `0` (which is the
  61 default) then all definitions behave as described.
  62 This can be used to construct a headerfile which only contains
  63 definitions, but, by default, yield only declarations. This provides one
  64 convenient single point to maintain flag configurations.
  65
  66 .Maintaining flags in a single header 'flags.h'
  67 [source,c]
  68 ----
  69 #include <nobug.h>
  70
  71 /*
  72  if not included from flags.c then declare the flags,
  73  else define them
  74  */
  75 #ifndef FLAGS_C
  76 #define NOBUG_DECLARE_ONLY 1
  77 #endif
  78
  79 /* use only DEFINE_FLAG here */
  80 NOBUG_DEFINE_FLAG(example);
  81
  82 /*
  83  Reset it to 0 to cause no trouble
  84  */
  85 #ifndef FLAGS_C
  86 #undef NOBUG_DECLARE_ONLY
  87 #define NOBUG_DECLARE_ONLY 0
  88 #endif
  89 ----
  90
  91 .flags.c
  92 [source,c]
  93 ----
  94 #define FLAGS_C
  95 #include "flags.h"
  96 ...
  97 ----
  98
  99
 100 .Logging Flag Initialization
 101
 102 Next you should call
 103
 104  NOBUG_INIT_FLAG(flagname)
 105
 106 or
 107
 108  NOBUG_INIT_FLAG_LIMIT(flagname, default)
 109
 110 once at the start of your program for each flag.
 111
 112 For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are initialized
 113 as in the xref:logdefaults[table above], while
 114 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the
 115 default target (depending on build level) to `level`.
 116