d01f4190d483e619c57e439245475323d6a6ea98
[nobug] / 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 hierachies 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^ Force declarations only; NOBUG_DECLARE_ONLY; force flag declarations
57
58 When `NOBUG_DECLARE_ONLY` defined to be `1` then all flag definitions here become
59 declarations only. When this is defined to be `0` (which is the default) then
60 all definitions behave as described. This can be used to construct a
61 headerfile which only contains definitions, but, by default, yield only
62 declarations. This provides one convenient single point to maintain flag
63 configurations.
64
65 .flags.h
66 [source,c]
67 ----
68 #include <nobug.h>
69
70 /*
71  if not included from flags.c then declare the flags,
72  else define them
73  */
74 #ifndef FLAGS_C
75 #define NOBUG_DECLARE_ONLY 1
76 #endif
77
78 /* use only DEFINE_FLAG here */
79 NOBUG_DEFINE_FLAG(example);
80
81 /*
82  Reset it to 0 to cause no trouble
83  */
84 #ifndef FLAGS_C
85 #undef NOBUG_DECLARE_ONLY
86 #define NOBUG_DECLARE_ONLY 0
87 #endif
88 ----
89
90 .flags.c
91 [source,C]
92 ----
93 #define FLAGS_C
94 #include "flags.h"
95 ...
96 ----
97
98
99 HEAD^ Logging Flag Initialization; INIT_FLAG; initialize log flags from environment
100
101 After a flag has been declared and defined, it has to be initialised:
102
103  NOBUG_INIT_FLAG(flagname)
104
105 or
106
107  NOBUG_INIT_FLAG_LIMIT(flagname, default)
108
109 Use either of these macros once at the begining your program for each flag.
110 This macros will parse the '$NOBUG_LOG' envirionment variable at runtime
111 initializing the given flag dynamically.
112
113 For flags defined with `NOBUG_DEFINE_FLAG(flagname)` the defaults are
114 initialized as in the xref:logdefaults[table above], while
115 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the default
116 target (depending on build level) to `level`.
117