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 Flags are generally used as follows:
   8
   9     . Declare the flag.
  10     . Define the flag.
  11     . Initialise the flag.
  12
  13 To declare a flag, it is suggested to do so in a header file:
  14 INDEX DECLARE_FLAG; DECLARE_FLAG; declaring a flag
  15
  16  NOBUG_DECLARE_FLAG(flagname)
  17
  18 The flag should then be defined most appropriately in some implementation file
  19 by using one of the following macros:
  20 INDEX DEFINE_FLAG; DEFINE_FLAG; defining a flag
  21
  22  NOBUG_DEFINE_FLAG(flagname)
  23
  24 or:
  25 INDEX DEFINE_FLAG_LIMIT; DEFINE_FLAG_LIMIT; defining a flag w/ log limit
  26
  27  NOBUG_DEFINE_FLAG_LIMIT(flagname, limit)
  28
  29 Moreover, macros are available that accept a 'parent' flag as a parameter, which is then
  30 used to initialize the defaults from another flag:
  31 INDEX DEFINE_FLAG_PARENT; DEFINE_FLAG_PARENT; defining a flag hierarchy
  32
  33  NOBUG_DEFINE_FLAG_PARENT(flagname, parent)
  34
  35 or
  36 INDEX DEFINE_FLAG_PARENT_LIMIT; DEFINE_FLAG_PARENT_LIMIT; defining a flag hierarchy, w/ log limit
  37
  38  NOBUG_DEFINE_FLAG_PARENT_LIMIT(flagname, parent, limit)
  39
  40 This can be used to create hierarchies of flags.
  41
  42
  43 HEAD^ C\++ support, C++ logflags; Cplusplus_logflags; C\++ support for log flags
  44
  45 Additional macros are available for applications written in C++:
  46
  47  NOBUG_CPP_DEFINE_FLAG(name)
  48  NOBUG_CPP_DEFINE_FLAG_PARENT(name, parent)
  49  NOBUG_CPP_DEFINE_FLAG_LIMIT(name, default)
  50  NOBUG_CPP_DEFINE_FLAG_PARENT_LIMIT(name, parent, default)
  51
  52 These macros statically initialize the flags when they are defined, there is no
  53 need to call `NOBUG_INIT_FLAG()` (see below).
  54
  55
  56 HEAD^ Logging Flag Initialization; INIT_FLAG; initialize log flags from environment
  57
  58 After a flag has been declared and defined, it has to be initialised:
  59
  60  NOBUG_INIT_FLAG(flagname)
  61
  62 or
  63
  64  NOBUG_INIT_FLAG_LIMIT(flagname, default)
  65
  66 Use either of these macros once at the begining your program for each flag.
  67 This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
  68 initializing the given flag dynamically.
  69
  70 For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
  71 initialized as in the xref:loggingleveldefaults[table above], while
  72 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
  73 target (depending on build level) to `level`.
  74
  75
  76 HEAD^ Force declarations only; NOBUG_DECLARE_ONLY; force flag declarations
  77
  78 When `NOBUG_DECLARE_ONLY` defined to be `1` then all flag definitions here become
  79 declarations only. When this is defined to be `0` (which is the default) then
  80 all definitions behave as described. This can be used to construct a
  81 headerfile which only contains definitions, but, by default, yield only
  82 declarations. This provides one convenient single point to maintain flag
  83 configurations.
  84
  85 .flags.h
  86 [source,c]
  87 ----
  88 #include <nobug.h>
  89
  90 /*
  91  if not included from flags.c then declare the flags,
  92  else define them
  93  */
  94 #ifndef FLAGS_C
  95 #define NOBUG_DECLARE_ONLY 1
  96 #endif
  97
  98 /* use only DEFINE_FLAG here */
  99 NOBUG_DEFINE_FLAG(example);
 100
 101 /*
 102  Reset it to 0 to cause no trouble
 103  */
 104 #ifndef FLAGS_C
 105 #undef NOBUG_DECLARE_ONLY
 106 #define NOBUG_DECLARE_ONLY 0
 107 #endif
 108 ----
 109
 110 .flags.c
 111 [source,C]
 112 ----
 113 #define FLAGS_C
 114 #include "flags.h"
 115 ...
 116 ----
 117