Some Pending cosmetics and small fixes
[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
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