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. Prior including this, a Build-level has to be choosen,
   5 Build-levels are discussed later, c.f., xref:buildlevel[buildlevel].
   6 Build-levels are used to define the amount of information NoBug provides to
   7 you. Maximum information is generally required while developing an application
   8 and the ALPHA build-level is most apropriate during this phase; whereas the
   9 released phase of an application will usually only require sparse information,
  10 for which the RELEASE build-level has been conceived.
  11
  12 A build-level must always be specified, otherwise the compiler will complain
  13 while attempting to compile your application.  You can specifiy a build level in
  14 one of two ways: use a define statement in one of your modules, or pass the
  15 build-level using the -D flag to your compiler.  Assuming we'd like to select
  16 the ALPHA build-level in your application, then your module would assume the
  17 following form:
  18
  19  #define EBUG_ALPHA
  20  #include <nobug.h>
  21
  22 Subsequently you'll have to link the appropriate library to your application.
  23
  24 A number of different libraries are available to link depending on whether you
  25 require to statically or dynamically link, or whether your application is multi
  26 or single threaded.  The link order is important on your link line.  Link the NoBug
  27 library 'after' your application's modules.  Here's how to statically link,
  28 single-threaded applications:
  29
  30 [source,sh]
  31 ----------------
  32 gcc -o mybinary  $(WHATEVER_FLAGS) \
  33        mymodules.o ... -lnobug
  34 ----------------
  35
  36 However, for more flexibility in selecting a build-level, you might wish to
  37 define various targets in your makefile, one for each build-level.  In such
  38 cases, the -D flag in your makefile is most appropriate; so your link line for
  39 an ALPHA build with multi-threaded support would look like the following:
  40
  41 [source,sh]
  42 ----------------
  43 gcc -o mybinary -DEBUG_ALPHA $(WHATEVER_FLAGS) \
  44        mymodules.o -lnobugmt
  45 ----------------
  46
  47 The NoBug libraries must be initialised before they can be used. To initialise
  48 it call the `NOBUG_INIT` macro, which must be used before any NoBug features
  49 can be used or any thread is created. This is discussed in more detail in the
  50 xref:multithreading[multithreading] chapter.
  51
  52 So putting all this together, our application using NoBug might look something
  53 like the following:
  54
  55
  56 [source,C]
  57 ----------------
  58 #define EBUG_ALPHA   /* If we don't use the -D Flag to cc */
  59 #include <nobug.h>   /* Include the NoBug API */
  60
  61 int main()
  62 {
  63         NOBUG_INIT;  /* Initialise NoBug libs */
  64
  65         ...
  66 }
  67 ----------------
  68
  69
  70
  71 Many aspects of NoBug can be configured by overriding macros before 'nobug.h' is
  72 included.
  73
  74
  75 HEAD~ Autotools Support;;
  76
  77 A project using NoBug can use autoconf to check for execinfo and
  78 valgrind:
  79
  80 [source,sh]
  81 ----------------
  82 AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
  83 PKG_CHECK_MODULES(VALGRIND, [valgrind],
  84                             [AC_DEFINE(HAVE_VALGRIND_H)])
  85 ----------------
  86
  87 For Multithreaded programs, you should also check for the availability of pthreads
  88 and flavour with the `ACX_PTHREAD` maxro, see:
  89
  90 +http://ac-archive.sourceforge.net/ac-archive/acx_pthread.html[]+
  91
  92 When the resulting `HAVE_PTHREAD`, `HAVE_EXECINFO_H` and
  93 `HAVE_VALGRIND_H` are defined by the configure script, the
  94 relevant features become available.
  95
  96 `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and `NOBUG_USE_EXECINFO` will be
  97 defined depeding on the information gathered by configuration. If you do not
  98 want to use any of these features in NoBug, you can override these macros by
  99 setting them to `0` before including 'nobug.h'.
 100
 101 If `NVALGRIND` is defined, there will be no support for valgrind.
 102
 103 There are many other macros which can be set and overridden by the user to
 104 control behavior. Your help would be appreciated in expanding this documentation
 105 if you find some features useful; or simply contact any of the authors.
 106
 107
 108 .Using Nobug from a Project using autoconf/automake
 109
 110 Here is a rather elaborate snippet how to put this all together into a
 111 `configure.ac` file:
 112
 113 [source,sh]
 114 ----------------
 115 # define autoheader templates for the config macros
 116 AH_TEMPLATE(EBUG_ALPHA,
 117         [Define to 1 for selecting NoBug ALPHA build level])
 118 AH_TEMPLATE(EBUG_BETA,
 119         [Define to 1 for selecting NoBug BETA build level])
 120 AH_TEMPLATE(NDEBUG,
 121         [Define to 1 for selecting NoBug RELEASE build level])
 122
 123 # set configure options up
 124 AC_ARG_ENABLE(alpha, AC_HELP_STRING([--enable-alpha],
 125                 [select NoBug ALPHA build level]),
 126         nobug_level=alpha
 127         AC_DEFINE(EBUG_ALPHA),
 128 [
 129 AC_ARG_ENABLE(beta, AC_HELP_STRING([--enable-beta],
 130                 [select NoBug BETA build level]),
 131         nobug_level=beta
 132         AC_DEFINE(EBUG_BETA),
 133 [
 134 AC_ARG_ENABLE(release, AC_HELP_STRING([--enable-release],
 135                 [select NoBug RELEASE build level]),
 136         nobug_level=release
 137         AC_DEFINE(NDEBUG),
 138
 139 # default to ALPHA
 140         nobug_level=alpha
 141         AC_DEFINE(EBUG_ALPHA)
 142 )])])
 143
 144 # check for required and optional packages
 145 ACX_PTHREAD
 146 AC_CHECK_HEADER([execinfo.h], AC_DEFINE(HAVE_EXECINFO_H))
 147 PKG_CHECK_MODULES(VALGRIND, [valgrind],
 148         AC_DEFINE(HAVE_VALGRIND_H))
 149
 150 # finally check for nobug itself, multithreaded here
 151 PKG_CHECK_MODULES(NOBUGMT_EXAMPLE, [nobugmt >= 201006.1],
 152         AC_DEFINE(HAVE_NOBUGMT_H),
 153         AC_MSG_ERROR([NoBug pkg-config metadata missing])
 154 )
 155 ----------------
 156