debug-trace-doc.h 2.04 KB
Newer Older
1 2 3 4
/**
\page subp_dbg_trace Debugging with macros and level

\section subp_dbg_trace_intro Introduction
Bergé's avatar
Bergé committed
5
The idea of this class and collection of MACROS is to specify
6 7 8 9
a level for a message, and record the message in a stream according to this
level. In addition there are mechanisms allowing that no time is wasted in
condition test. You can therefore let the debugging messages inside the code
without impact on performances.
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

\section subp_dbg_trace_set_on_macros Setting up dgDEBUG macros

To allow message display the entity must be compiled with the macro
\code
#define VP_DEBUG 1
\endcode
Commenting or removing this macro disable all the messages specified
by the following macros.

The level up to which the messages are accepted for display is
specified by:
\code
#define VP_DEBUG_MODE 50
\endcode

In the constructor of the entity, the file where all the messages
are written is specified by:
\code
  dynamicgraph::dgDEBUGFLOW.openFile("/tmp/dynamic-graph-traces.txt");
\endcode

\section subp_dbg_trace_using_macros Using dgDEBUG macros

34 35 36
To print that the beginning of a method is being executed use the following
macros: \code dgDEBUGIN(5); \endcode 5 here specifies the minimum level that you
be specified by VP_DEBUG_MODE for this message to be displayed.
37 38 39 40 41

It will generate the following output:
\code
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#46) :# In {
\endcode
Bergé's avatar
Bergé committed
42
The output displays the name of the source file, the name of the method,
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
the line where is the macro, and the message itself.

When going out of the method:
\code
    dgDEBUGOUT(5);
\endcode

This generates the following output:
\code
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#54) :# Out }
\endcode

A message inside the code is written through:
\code
      dgDEBUG(5) << "Here is a test" << std::endl;
\endcode

This generates the following output:
\code
62 63
/path_to/dynamic-graph/tests/debug-trace.cpp: testDebugTrace(#52) :Here is a
test \endcode
64 65 66 67 68 69

\section subp_dbg_trace_wrk_exp Working example

A full working example is given here:
\include ../tests/debug-trace.cpp
 */