doc/using.txt

   1 HEAD- Using NoBug;;
   2
   3 Your application will have to include the header file 'nobug.h' before NoBug
   4 can be used:
   5
   6  #include <nobug.h>
   7
   8
   9 Once you've included the NoBug API in your application, you'll then have to select
  10 a 'build-level'.  Build-levels are discussed later, c.f.,
  11 xref:buildlevel[buildlevel].   Build-levels are used to define the amount of
  12 information NoBug provides to you.  Maximum information is generally required while
  13 developing an application and the ALPHA build-level is most apropriate during
  14 this phase; whereas the released phase of an application will usually only require
  15 sparse information, for which the RELEASE build-level has been conceived.
  16
  17 A build-level must always be specified, otherwise the compiler will complain
  18 while attempting to compile your application.  You can specifiy a build level in
  19 one of two ways: use a define statement in one of your modules, or pass the
  20 build-level using the -D flag to your compiler.  Assuming we'd like to select
  21 the ALPHA build-level in your application, then your module would assume the
  22 following form:
  23
  24
  25  #define EBUG_ALPHA
  26  #include <nobug.h>
  27
  28
  29
  30 Subsequently you'll have to link the appropriate library to your application.
  31
  32 A number of different libraries are available to link depending on whether you
  33 require to statically or dynamically link, or whether your application is multi
  34 or single threaded.  The link order is important on your link line.  Link the NoBug
  35 library 'after' your application's modules.  Here's how to statically link,
  36 single-threaded applications:
  37
  38 [source,sh]
  39 ----------------
  40 gcc -o mybinary $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobug.a
  41 ----------------
  42
  43 However, for more flexibility in selecting a build-level, you might wish to
  44 define various targets in your makefile, one for each build-level.  In such
  45 cases, the -D flag in your makefile is most appropriate; so your link line for
  46 an ALPHA build with multi-threaded support would look like the following:
  47
  48 [source,sh]
  49 ----------------
  50 gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) mymodule1.o ... mymodulen.o  ..../libs/libnobugmt.a
  51 ----------------
  52
  53 Both libraries must be initialised  before they can be used.  There are a number
  54 of different ways to initialise the NoBug libraries.  One of the easiest ways
  55 to initialise the NoBug libraries is to use the `NOBUG_INIT` macro, which must
  56 be used before any features can be used or any thread is created. This is
  57 discussed in more detail in the xref:multithreading[multithreading] chapter.
  58
  59 So putting all this together, our application using NoBug might look something
  60 like the following:
  61
  62
  63 [source,sh]
  64 ----------------
  65 #include <nobug.h>   /* Include the NoBug API */
  66 #define EBUG_ALPHA   /* If we have not used the -D Flag in our makefile */
  67
  68 int main()
  69 {
  70         NOBUG_INIT;  /* Initialise NoBug libs */
  71
  72         ...
  73 }
  74 ----------------
  75
  76
  77
  78
  79
  80
  81 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
  82 included.
  83
  84 A project using NoBug can use autoconf to check for execinfo and
  85 valgrind:
  86
  87  AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
  88  PKG_HAVE_DEFINE_WITH_MODULES(VALGRIND, [valgrind])
  89
  90 For Multithreaded programs, you should also check for the availability of pthreads
  91 and flavour
  92
  93  ACX_PTHREAD
  94
  95 When the resulting `HAVE_PTHREAD`, `HAVE_EXECINFO_H` and
  96 `HAVE_VALGRIND_H` are defined by the configure script, the
  97 relevant features become available.
  98
  99 NoBug then defines `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and
 100 `NOBUG_USE_EXECINFO` to 1. If you do not want to use any of these features in
 101 NoBug, you can override these macros by setting to 0 before including nobug.h.
 102
 103 If `NVALGRIND` is defined, there will be no support for valgrind.
 104
 105
 106
 107 There are many other macros which can be set and overridden by the user to
 108 control behavior. Your help would be appreciated in expanding this documentation
 109 if you find some features useful; or simply contact any of the authors.
 110
 111
 112
 113 .Using Nobug from a Project using autoconf
 114 [source,sh]
 115 ----------------
 116 PKG_CHECK_MODULES(NOBUGMT_LUMIERA, [nobugmt >= 0.3rc1],
 117                                  AC_DEFINE(HAVE_NOBUGMT_H),
 118                                  AC_MSG_ERROR([NoBug pkg-config metadata missing])
 119 )
 120 ----------------
 121