doc/using.txt

   1 Using NoBug
   2 -----------
   3
   4 You can make NoBug features available either by installing it as described
   5 above or by shipping the nobug sources along with your project.
   6
   7 To use NoBug, some controlling preprocessor macros have to be defined. The
   8 nobug.h header should then be included.
   9
  10 A project using NoBug should use autoconf to check for execinfo.h and valgrind/
  11 valgrind.h
  12
  13  AC_CHECK_HEADERS([execinfo.h valgrind/valgrind.h])
  14
  15 For Multithreaded programs, you should also check for pthread.h.
  16
  17 When the resulting `HAVE_PTHREAD_H`, `HAVE_EXECINFO_H` and
  18 `HAVE_VALGRIND_VALGRIND_H` are defined by the configure script, the
  19 corresponding features become available.
  20
  21 NoBug then defines `NOBUG_USE_PTHREAD`, `NOBUG_USE_VALGRIND` and
  22 'NOBUG_USE_EXECINFO' to 1. If you do not want to use any of these features in
  23 NoBug, you can override these macros to 0 before including nobug.h.
  24
  25 If `NVALGRIND` is defined, valgrind support will not be available.
  26
  27 There are many other macros which can be set and overridden by the user to
  28 control behavior. Please help completing this documentation if you
  29 find them useful.
  30
  31 To use NoBug with single threaded programmes, link 'libnobug' to your project;
  32 multi-threaded programmes should link with 'libnobugmt'. The Library must be
  33 initialized with `NOBUG_INIT` before any features can be used or a thread is
  34 created. This is discussed in more detail at the
  35 xref:multithreading[multithreading] chapter.
  36
  37 Header and Initialisation
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~
  39 The project source file will have to include 'nobug.h', and Nobug will have to be
  40 initialised using `NOBUG_INIT` before any NoBug features can be used
  41 or when you use xref:logflags[logging flags], these can be initialized
  42 with `NOBUG_INIT_FLAG()`, calling `NOBUG_INIT` is then optional.
  43 See the xref:initexample[initialization example] further down.
  44