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