reviewd, reworded and fixed some documentation
authorChristian Thaeter <ct@pipapo.org>
Mon, 9 Aug 2010 05:18:21 +0000 (07:18 +0200)
committerChristian Thaeter <ct@pipapo.org>
Mon, 9 Aug 2010 05:18:21 +0000 (07:18 +0200)
13 files changed:
doc/additional.txt
doc/buildinstall.txt
doc/buildlevels.txt
doc/initialization.txt
doc/logconfiguration.txt
doc/logflags.txt
doc/logflagsenv.txt
doc/logflagsexample.txt [new file with mode: 0644]
doc/logformat.txt [new file with mode: 0644]
doc/logging.txt
doc/nobug_manual.conf
doc/using.txt
src/nobug.c

index 0350f97..a7f8899 100644 (file)
@@ -1,4 +1,4 @@
-HEAD~ Checking for Additional Tools;;
+HEAD~ Additional Tools;;
 
 Various peripheral tools can be used by NoBug depending on the requirements
 of the application and the detail desired by the user.  Such tools can provide
@@ -10,31 +10,6 @@ excluding such tools.
 At the moment NoBug supports the optional inclusion of gdb, valgrind and support
 for multi-threaded applications and the information that can be provided by
 these tools.  However, support for other tools may be supplied in the future,
-e.g. the dbx debugger on OpenSolaris. 
-
-Such tools can be easily queried on the system and if they are available on a
-particular system, they can be used by NoBug to provide even more information on
-the application using NoBug.  If such tools are not available or are not
-required by the user for one reason or other, then NoBug will happily function
-as usual, just without the extra information.
-
-Testing the availability of such tools on a particular system can be achieved
-using autoconf, as illustrated in the following:
-
-`*NOBUG_USE_VALGRIND*`::
-   `1`:: Use valgrind
-   `0`:: Do not use valgrind
-
-`*NOBUG_USE_PTHREAD*`::
-   `1`:: Support for multi-thread applications
-   `0`:: Single-threaded applications
-
-`*NOBUG_USE_EXECINFO*`::
-   `1`:: Backtrace information
-   `0`:: No backtrace information
-
-These macros are then automatically defined when the configuration system
-provides the associated `HAVE_*` macros, but can then be overridden by the user,
-depending on the user's requirements.
+e.g. the dbx debugger on OpenSolaris.
 
 
index 75c7cc4..184355b 100644 (file)
@@ -49,7 +49,8 @@ will work:
  $ ../configure
  $ make
  $ make check           # optional, run the testsuite
- $ make install         # depending on distribution and setup, do this as root
+ $ make install         # to be done as root,
+                        # depending on distribution and setup
 
 
 HEAD== Development Version via git;;
@@ -108,7 +109,7 @@ Currently, NoBug installs the following:
   * The `nobug_rbdump` utility to inspect NoBug ringbuffers.
 
 
-PARA Generating This Documentation;;
+HEAD== Generating This Documentation;;
 
 There are Makefile targets for generating the documentation, Either one of the
 following does what you may expect:
@@ -117,7 +118,7 @@ following does what you may expect:
 
 building the documentation has quite some more dependencies than building
 NoBug itself. Unless you are a packager you may want to refer to the online
-doc or the shipped 'README' which is actually this full nobug manual.
-Generating the documentation requires: gawk, asciidoc, graphviz and some
-toolchains to further process docbook (dblatex, ...).
+documentation or the shipped 'README' which is this complete nobug reference
+manual in text form. Generating the documentation requires: gawk, asciidoc,
+graphviz and some toolchains to further process docbook and latex.
 
index b623d85..f7e66e8 100644 (file)
@@ -8,24 +8,30 @@ an error while compiling will occur.
 
   *ALPHA*::
        This debugging level is envisaged for the development phase of a project
-       where exhaustive testing and logging are required.
+       where exhaustive testing and logging are required. All NoBug features
+        are enabled.
   *BETA*::
         This debugging level is more appropriate for projects beyond the
        development phase and ready for trials in the field and users willing to
-       test the software.
+       test the software. The most expensive debugging features are disabled
+       on this level.
   *RELEASE*::
-       This level is for final, end-users.
+       This level is for final, end-users. Logging is mostly retained but
+       assertions and other checking is disabled.
 
 .Select a Build Level
-A logging level can be selected by either using a define in one of the
-applications' modules, or by passing the appropriate level using the -D switch
+A logging level can be selected by either using a define prior including
+`nobug.h`, or by passing the appropriate level using the -D switch
 to the compiler:
 
-    *ALPHA*::   -DEBUG_ALPHA (`#define EBUG_ALPHA`)
+    *ALPHA*::
+       `-DEBUG_ALPHA` / `#define EBUG_ALPHA`
 
-    *BETA*::    -DEBUG_BETA (`#define EBUG_BETA`)
+    *BETA*::
+       `-DEBUG_BETA` / `#define EBUG_BETA`
 
-    *RELEASE*:: -DNDEBUG (`#define NDEBUG`)
+    *RELEASE*::
+       `-DNDEBUG` / `#define NDEBUG`
 
 If none of the above switches has been set, NoBug will abort the
 compilation with an error.
index dc3ec83..3fd0453 100644 (file)
@@ -1,29 +1,32 @@
 HEAD- Initialization;;
 
-HEAD++ Global init;;
+HEAD++ Global Initialization;;
 
-Before anything from NoBug can be used, NoBug must be initialised.  This is
-performed by calling one of the `NOBUG_INIT_` macros.
-
-The simpliest such macro among the initialising set is the following:
-
-  NOBUG_INIT()
+Before anything from NoBug can be used, NoBug must be initialised. This
+is archived by calling the `NOBUG_INIT()` macro before using any other of the
+NoBug facilities.
 
 `NOBUG_INIT` can be called more than once, subsequent calls will be a no-op,
 thus initialising in main and in libraries won't interfere with one another.
 
-In other words, `NOBUG_INIT` is usually the first call to NoBug.
+Care must be taken when one already using NoBug features from dynamic
+initialized things in C++, one has to ensure that NoBug gets initialized first
+possibly by pulling up a singleton at very first.
+
+
+HEAD== Destroying NoBug;;
 
-.Destroying NoBug
 Since NoBug is intended to be available throughout its whole lifetime,
 destroying it is not to be advised. Nevertheless, there is a destroy function
- void nobug_destroy (void)
+
+ void nobug_destroy (void);
 
 to shutdown NoBug, and this frees all resources associated with it.
 This is mostly used in the NoBug testsuite itself to check for leaks,
 and it might be useful for other programs which employ some kind of
 leak checker.
 
+
 HEAD== Init logging Flags;;
 
 If you want to use environment variable controlled debuging, then you have to
@@ -39,6 +42,7 @@ or one of the C++ compatibility macros.
 
 This is documented later in the xref:logconfig[logging configuration] chapter.
 
+
 HEAD== Threads;;
 
 In Multithreaded programs you should assign an identifier to each
@@ -47,16 +51,19 @@ appended with an underscore and a incrementing integer. It is is created with:
 
   NOBUG_THREAD_ID_SET(name)
 
-Calling `NOBUG_THREAD_ID_SET("worker")` will yield in a thread
+Calling `NOBUG_THREAD_ID_SET("worker")` will result in a thread
 identifier 'worker_1' for example.
 
 If you don't set an identifier, then NoBug will assign an automatic one.
 This is further documented in the xref:multithreading[multi threading]
 section of this manual.
 
-[[initexample]]
-.Initialization
-[source,c]
+
+PARA Initialization example; initexample; initialize NoBug, example
+
+Thus the boilerplate code to pulling up NoBug looks like:
+
+[source,C]
 -------------------------------------------------------
 #include "nobug.h"
 NOBUG_DEFINE_FLAG(example);
index fcdbfe2..af7f700 100644 (file)
@@ -22,23 +22,25 @@ message is more severe or the same as a defined limit.
 Depending on the build level, there is a default logging target and a default
 limit which is selected when the user doesn't specify one.
 
-The following default limits are available:
-
-  * In *ALPHA* builds, `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
-  * In *BETA* builds, `NOBUG_LOG_LIMIT_BETA` is used and defaults to `LOG_WARNING`
-  * In *RELEASE* builds, `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
-
-The default targets are:
-
-  * In *ALPHA* builds, `NOBUG_LOG_TARGET_ALPHA` is used which defaults to
-    `NOBUG_TARGET_CONSOLE`
-  * In *BETA* builds, `NOBUG_LOG_TARGET_BETA` is used and defaults to
-    `NOBUG_TARGET_FILE`
-  * In *RELEASE* builds, `NOBUG_LOG_TARGET_RELEASE` is used and defaults to
-    `NOBUG_TARGET_SYSLOG`
-
-
-You can override all these values with your own values. As an alternative,
-`NOBUG_LOG_LIMIT` and `NOBUG_LOG_TARGET` can be defined before
-including "nobug.h" to override all defaults.
+PARA The following default limits are;limits, logging;default logging limits
+
+  In *ALPHA* builds::
+     `NOBUG_LOG_LIMIT_ALPHA` is used which defaults to `LOG_INFO`
+  In *BETA* builds::
+     `NOBUG_LOG_LIMIT_BETA` is used and defaults to `LOG_WARNING`
+  In *RELEASE* builds::
+     `NOBUG_LOG_LIMIT_RELEASE` is used and defaults to `LOG_CRIT`
+
+PARA The default targets are;targets, logging;default logging targets
+
+  In *ALPHA* builds::
+    `NOBUG_LOG_TARGET_ALPHA` defaulting to `NOBUG_TARGET_CONSOLE`
+  In *BETA* builds::
+     `NOBUG_LOG_TARGET_BETA` defaulting to `NOBUG_TARGET_FILE`
+  In *RELEASE* builds::
+     `NOBUG_LOG_TARGET_RELEASE` defaulting to `NOBUG_TARGET_SYSLOG`
+
+You can override all these values with other limits or targets before
+including 'nobug.h'. As an alternative, `NOBUG_LOG_LIMIT` and
+`NOBUG_LOG_TARGET` can be defined to override all defaults at once.
 
index 0865fe6..b4346e2 100644 (file)
@@ -1,7 +1,7 @@
 HEAD~ Log Flags; logflags; define hierarchies for logging output
 
 Flags are used to inform NoBug about subsystems/modules or even finer
-grained sections of the code. These are referred to as 'channels' in other 
+grained sections of the code. These are referred to as 'channels' in other
 logging libraries.
 
 A flag should be declared in a headerfile using the following mechanism:
@@ -36,7 +36,7 @@ INDEX DEFINE_FLAG_PARENT_LIMIT; DEFINE_FLAG_PARENT_LIMIT; defining a flag hierar
 This can be used to create hierachies of flags
 
 
-PARA C++ support, C++ logflags; Cplusplus_logflags; C++ support for log flags
+PARA C\++ support, C++ logflags; Cplusplus_logflags; C\++ support for log flags
 
 Additional macros are available for applications written in C++:
 
@@ -45,23 +45,18 @@ Additional macros are available for applications written in C++:
  NOBUG_CPP_DEFINE_FLAG_LIMIT(name, default)
  NOBUG_CPP_DEFINE_FLAG_PARENT_LIMIT(name, parent, default)
 
-These macros statically initialize the flags when they are defined, there is no
-need to call `NOBUG_INIT_FLAG()` (see below).
+These macros initialize the flags when they are defined, there is no need to
+call `NOBUG_INIT_FLAG()` (see below).
 
 
 .Force declarations only
 
-When the the following preprocessor constant is defined to be `1`:
-
-INDEX DECLARE_ONLY; DECLARE_ONLY; force flag declarations only
- NOBUG_DECLARE_ONLY
-
-then *all* definitions here (`NOBUG_DEFINE_*`)
-become declarations only.  When this is defined to be `0` (which is the
-default) then all definitions behave as described.
-This can be used to construct a headerfile which only contains
-definitions, but, by default, yield only declarations. This provides one
-convenient single point to maintain flag configurations.
+When `INDEX DECLARE_ONLY` defined to be `1` then *all* definitions here
+(`NOBUG_DEFINE_*`) become declarations only. When this is defined to be `0`
+(which is the default) then all definitions behave as described. This can be
+used to construct a headerfile which only contains definitions, but, by
+default, yield only declarations. This provides one convenient single point to
+maintain flag configurations.
 
 .Maintaining flags in a single header 'flags.h'
 [source,c]
@@ -89,7 +84,7 @@ NOBUG_DEFINE_FLAG(example);
 ----
 
 .flags.c
-[source,c]
+[source,C]
 ----
 #define FLAGS_C
 #include "flags.h"
index f7cc95f..9d4e9ef 100644 (file)
@@ -1,26 +1,26 @@
 HEAD~ Control what gets logged; NOBUG_ENV; environment variable for loging control
 
-The `NOBUG_INIT_FLAG...` calls parsing the environment variable
-'NOBUG_LOG' to configure what gets logged at runtime. The syntax is as
+Calling the `NOBUG_INIT_FLAG...()` macros parsing the environment variable
+'$NOBUG_LOG' to configure what gets logged at runtime. The syntax is as
 following:
 
 .Formal Syntax for log control
 [source,prolog]
 ----
- logdecl_list --> logdecl, any( ',' logdecl_list).
+logdecl_list --> logdecl, any( ',' logdecl_list).
 
- logdecl --> flag, opt(limitdecl, any(targetdecl)).
+logdecl --> flag, opt(limitdecl, any(targetdecl)).
 
- flag --> "identifier of a flag".
+flag --> "identifier of a flag".
 
- limitdecl --> ':', "LIMITNAME".
+limitdecl --> ':', "LIMITNAME".
 
- targetdecl --> '@', "targetname", opt(targetopts).
+targetdecl --> '@', "targetname", opt(targetopts).
 
- targetopts --> '(', "options for target", ')', opt(targetopts).
+targetopts --> '(', "options for target", ')', opt(targetopts).
 ----
 
-Roughly speaking, 'NOBUG_LOG' contains a comma separated list of declarations for
+Roughly speaking, '$NOBUG_LOG' contains a comma separated list of declarations for
 flags which are the name of the flag followed by a limit which is written in
 all uppercase letters and preceeded by a colon, followed by target declarations
 which are names of the targets, introduced by a at sign. Target declarations
@@ -33,31 +33,52 @@ redefined in future.
 
 The Following options are available:
 
- `@ringbuffer`::
-   `(file=_filename_)`:: set filename backing the ringbuffer
-   `(size=_nnn_)`::      set size of the ringbuffer
-   `(append)`::          don't erase existing ringbuffer
-   `(keep)`::            keep file after application end
-   `(temp)`::            unlink file instantly at creation
-
- `@console`::
-   `(fd=n)`::            redirect console output to fd n
-
- `@file`::
-   `(name=_filename_)`:: log to filename
-   `(append)`::          append to (existing) log
-
- `@syslog`::
-   `(ident=_name_)`::    global prefix for syslog
-   `(cons)`::            log to system console if syslog is down
-   `(pid)`::             include pid in log
-   `(perror)`::          log to stderr as well
-
-
-.How the NOBUG_LOG is used
+`@ringbuffer`::
+  `(file=`'filename'`)`:::
+    set 'filename' for backing the ringbuffer
+  `(size=`'nnn'`)`:::
+    set size of the ringbuffer to 'nnn' byted, rounded up to the next page
+    boudary
+  `(append)`:::
+    don't erase existing ringbuffer, start where it left off
+  `(keep)`:::
+    keep file after application end
+  `(temp)`:::
+    unlink file instantly at creation
+
+The default ringbuffer is a temporary file in `/tmp` with the `temp` option.
+This means it will not be accessible.
+
+
+`@console`::
+  `(fd=`'n'`)`:::
+    redirect console output to fd 'n'
+
+When running under a debugger, then NoBug tries to use the debugger facilities
+to print console messages.
+
+`@file`::
+  `(name=`'filename'`)`:::
+    log to 'filename'
+  `(append)`:::
+    append to (existing) logfile
+
+`@syslog`::
+  `(ident=`'name'`)`:::
+    global prefix for syslog
+  `(cons)`:::
+    log to system console if syslog is down
+  `(pid)`:::
+    include the process identifier in the log
+  `(perror)`:::
+    log to stderr as well (Not available on all systems)
+
+
+.How $NOBUG_LOG is used
 [source,sh]
 ----
-# set the limit of the default target a default limit (see table above)
+# set limit to the default target and default limit
+# (see table above)
 NOBUG_LOG='flag,other'
 
 # set the limit of the default target to DEBUG
@@ -67,35 +88,6 @@ NOBUG_LOG='flag:DEBUG'
 NOBUG_LOG='flag:DEBUG@console@syslog'
 
 # trace 'other' to a persistent ringbuffer
-NOBUG_LOG='other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
+NOBUG_LOG=\
+ 'other:TRACE@ringbuffer(file=log.rb)(size=8192)(keep)'
 ----
-
-.Using log flags (example.c)
-[source,c]
-----
-#include "nobug.h"
-
-NOBUG_DEFINE_FLAG (test);
-
-int main()
-{
-   /* NOBUG_INIT;  // not needed because of NOBUG_INIT_FLAG */
-   NOBUG_INIT_FLAG (test);
-
-   TRACE (test, "Logging enabled");
-   TRACE (NOBUG_ON, "Always on");
-}
-----
-
-.test it:
-[source,sh]
-----
-$ cc -DEBUG_ALPHA -lnobug example.c
-$ ./a.out
-0000000002: TRACE: example.c:11: main: Always on
-
-$ NOBUG_LOG=test:TRACE ./a.out
-0000000001: TRACE: example.c:10: main: Logging enabled
-0000000002: TRACE: example.c:11: main: Always on
-----
-
diff --git a/doc/logflagsexample.txt b/doc/logflagsexample.txt
new file mode 100644 (file)
index 0000000..6c81427
--- /dev/null
@@ -0,0 +1,31 @@
+
+.Using log flags (example.c)
+[source,c]
+----
+#include <nobug.h>
+
+NOBUG_DEFINE_FLAG (test);
+
+int main()
+{
+   NOBUG_INIT;
+   NOBUG_INIT_FLAG (test);
+
+   TRACE (test, "Logging enabled");
+   TRACE (NOBUG_ON, "Always on");
+   return 0;
+}
+----
+
+.test it:
+[source,sh]
+----
+$ cc -DEBUG_ALPHA -lnobug example.c
+$ ./a.out
+0000000003: TRACE: example.c:11: -: main: Always on
+
+$ NOBUG_LOG=test:TRACE ./a.out
+0000000003: TRACE: example.c:10: -: main: Logging enabled
+0000000004: TRACE: example.c:11: -: main: Always on
+----
+
diff --git a/doc/logformat.txt b/doc/logformat.txt
new file mode 100644 (file)
index 0000000..8a011d5
--- /dev/null
@@ -0,0 +1,58 @@
+HEAD~ Log Line Format; logformat; format of a log line
+
+Logging follows a rather rigid format and is not configurable. This is
+intentional to make it easier to compare and process logs afterwards. NoBug is
+designed with the goal to effectively do very fine grained logging and then
+analyze this logs later, either manually or with further tools.
+
+A typical log looks like:
+
+ 0000000003: TRACE: test.c:10: thread_1: main: message
+ 0000000003! TRACE: test.c:10: thread_1: main: continued
+ 0000000005: NOTICE: test.c:15: thread_1: main: next
+
+The components are delimited by ": " or in one case by "! " are as following:
+
+ . *Sequence Number* +
+   Each logging event increments a counter, for preformance (and privacy)
+   reasons we do not use timestamps here. The sequence number is represented by
+   ten decimal digits, overflows are not specially handled. There is a special
+   case that when the final message (see below) spans some log lines, the
+   delimiter after the sequence number is a "! " and not ": ". The sequence
+   numbers in a log can be sparse because not every event is send to the log,
+   the left out lines are still available in the ringbuffer.
+
+ . *NoBug Facility* +
+   Describes what NoBug macro produced the output. This can be a simple
+   annotation or logging as well as assertions or one of the more complex
+   NoBug facilities.
+
+ . *File and Linenumber* +
+   The filename is only printed without it's path. This is important for some
+   reasons. First it makes the log vastly more readable and second depending
+   on source location and build system and configuration thereof paths are not
+   easily reproducible, this makes it hard to use simple tools like grep or
+   diff on logs generated on different systems. For some messages the filename
+   and/or the linenumber is not available or meaningless, a "-" is used then.
+
+ . *Thread Identifier* +
+   Shows which thread generated this message. The single threaded version of
+   NoBug uses always "-".
+
+ . *Function Name* +
+   Gives the function in which the logging occured. For a lot macros it is
+   possible to pass a context (file, line and function name) around to make it
+   possible to delegate validation and logging to some special functions while
+   still being able to present the context where the call originated. NoBug
+   only uses the function name as identifier here no pretty printed prototype
+   or demangled C++ method. The reason for this is that neither is well
+   specified an may yield to non unique results which may even interfere with
+   the logging format syntax and thus make it very unreliable to write tools
+   to process logs.
+
+ . *Message* +
+   The rest of the log line is the user-defined and optional message part.
+   There are no constraints on the format and one should constrain himself to
+   print only meaningful textual information. Embedded newlines will always be
+   translated into a new logging line as shown in the example above.
+
index 8df700e..c785faf 100644 (file)
@@ -5,7 +5,7 @@ grained control over these log messages to display only interesting information
 without loosing details.
 
 Log messages can be routed to various destinations.  The following destintaions
-are available: 
+are available:
 
   *RINGBUFFER*::
         The underlying storage backend. Messages are appended to the
@@ -27,13 +27,14 @@ are available:
 
   *APPLICATION*::
         There are hooks which allow the programmer to catch logmessages and
-        display them in an application which are defined by the application.
+        display them in an application defined way.
 
 Each logmessage has a priority describing its severity in the same way as
 syslog messages do.
 
 All non-fatal messages are associated with a programmer defined flag describing
-the source of the message (subsystem, module, ...).
+the source of the message (subsystem, module, ...). Other logging systems
+often name this 'channels'.
 
 Putting this all together: A user can define which source/flag will be logged at
 what priority level and to which destination. To make this all easier, NoBug
index 0708c54..867d04f 100644 (file)
 
 //=predefflags
 
+//=logflagsexample
+
+//=logformat
+
 //=macros
 
+
 //=parametertable
 
 //=srccontext
index b413be3..49503b2 100644 (file)
@@ -37,33 +37,35 @@ single-threaded applications:
 
 [source,sh]
 ----------------
-gcc -o mybinary $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobug.a 
+gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
+       mymodules.o ... -lnobug
 ----------------
 
 However, for more flexibility in selecting a build-level, you might wish to
 define various targets in your makefile, one for each build-level.  In such
 cases, the -D flag in your makefile is most appropriate; so your link line for
-an ALPHA build with multi-threaded support would look like the following: 
+an ALPHA build with multi-threaded support would look like the following:
 
 [source,sh]
 ----------------
-gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobugmt.a 
+gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
+       mymodules.o -lnobugmt
 ----------------
 
 Both libraries must be initialised  before they can be used.  There are a number
 of different ways to initialise the NoBug libraries.  One of the easiest ways
 to initialise the NoBug libraries is to use the `NOBUG_INIT` macro, which must
 be used before any features can be used or any thread is created. This is
-discussed in more detail in the xref:multithreading[multithreading] chapter.  
+discussed in more detail in the xref:multithreading[multithreading] chapter.
 
 So putting all this together, our application using NoBug might look something
 like the following:
 
 
-[source,sh]
+[source,C]
 ----------------
+#define EBUG_ALPHA   /* If we don't use the -D Flag to cc */
 #include <nobug.h>   /* Include the NoBug API */
-#define EBUG_ALPHA   /* If we have not used the -D Flag in our makefile */
 
 int main()
 {
@@ -76,46 +78,89 @@ int main()
 
 
 
-
-
 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
 included.
 
+
+HEAD~ Autotools Support;;
+
 A project using NoBug can use autoconf to check for execinfo and
 valgrind:
 
- AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
- PKG_HAVE_DEFINE_WITH_MODULES(VALGRIND, [valgrind])
+[source,sh]
+----------------
+AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
+PKG_CHECK_MODULES(VALGRIND, [valgrind],
+                            [AC_DEFINE(HAVE_VALGRIND_H)])
+----------------
 
 For Multithreaded programs, you should also check for the availability of pthreads
-and flavour
+and flavour with the `ACX_PTHREAD` maxro, see:
 
- ACX_PTHREAD
+ http://ac-archive.sourceforge.net/ac-archive/acx_pthread.html[]
 
 When the resulting `HAVE_PTHREAD`, `HAVE_EXECINFO_H` and
 `HAVE_VALGRIND_H` are defined by the configure script, the
 relevant features become available.
 
-NoBug then defines `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and
-`NOBUG_USE_EXECINFO` to 1. If you do not want to use any of these features in
-NoBug, you can override these macros by setting to 0 before including nobug.h.
+`NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and `NOBUG_USE_EXECINFO` will be
+defined depeding on the information gathered by configuration. If you do not
+want to use any of these features in NoBug, you can override these macros by
+setting them to `0` before including 'nobug.h'.
 
 If `NVALGRIND` is defined, there will be no support for valgrind.
 
-
-
 There are many other macros which can be set and overridden by the user to
 control behavior. Your help would be appreciated in expanding this documentation
 if you find some features useful; or simply contact any of the authors.
 
 
+.Using Nobug from a Project using autoconf/automake
+
+Here is a rather elaborate snippet how to put this all together into a
+`configure.ac` file:
 
-.Using Nobug from a Project using autoconf
 [source,sh]
 ----------------
-PKG_CHECK_MODULES(NOBUGMT_LUMIERA, [nobugmt >= 0.3rc1],
-                                 AC_DEFINE(HAVE_NOBUGMT_H),
-                                 AC_MSG_ERROR([NoBug pkg-config metadata missing])
+# define autoheader templates for the config macros
+AH_TEMPLATE(EBUG_ALPHA,
+        [Define to 1 for selecting NoBug ALPHA build level])
+AH_TEMPLATE(EBUG_BETA,
+        [Define to 1 for selecting NoBug BETA build level])
+AH_TEMPLATE(NDEBUG,
+        [Define to 1 for selecting NoBug RELEASE build level])
+
+# set configure options up
+AC_ARG_ENABLE(alpha, AC_HELP_STRING([--enable-alpha],
+                [select NoBug ALPHA build level]),
+        nobug_level=alpha
+        AC_DEFINE(EBUG_ALPHA),
+[
+AC_ARG_ENABLE(beta, AC_HELP_STRING([--enable-beta],
+                [select NoBug BETA build level]),
+        nobug_level=beta
+        AC_DEFINE(EBUG_BETA),
+[
+AC_ARG_ENABLE(release, AC_HELP_STRING([--enable-release],
+                [select NoBug RELEASE build level]),
+        nobug_level=release
+        AC_DEFINE(NDEBUG),
+
+# default to ALPHA
+        nobug_level=alpha
+        AC_DEFINE(EBUG_ALPHA)
+)])])
+
+# check for required and optional packages
+ACX_PTHREAD
+AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
+PKG_CHECK_MODULES(VALGRIND, [valgrind],
+        AC_DEFINE(HAVE_VALGRIND_H))
+
+# finally check for nobug itself, multithreaded here
+PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= ],
+        AC_DEFINE(HAVE_NOBUGMT_H),
+        AC_MSG_ERROR([NoBug pkg-config metadata missing])
 )
 ----------------
 
index a5cc52b..bedde33 100644 (file)
@@ -64,8 +64,8 @@ struct nobug_flag nobug_flag_NOBUG_ANN =
 //predefflags PARA nobug (flag); nobug_flag; log flag used to show nobug actions
 //predefflags
 //predefflags Actions on NoBug itself will be logged under the `nobug` flag itself.
-//predefflags When you want to see whats going on (useful to check if you call
-//predefflags `NOBUG_INIT_FLAG()` on all flags) you can enable it with `NOBUG_LOG=nobug:TRACE`.
+//predefflags To see whats going on you can enable it with `NOBUG_LOG=nobug:TRACE`.
+//predefflags This is particulary useful to check if `NOBUG_INIT_FLAG()` is called on all flags.
 //predefflags
 */
 struct nobug_flag nobug_flag_nobug =