1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
4 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
5 <TITLE>SALOME Kernel resources for developer: Trace and debug Utilities</TITLE>
6 <LINK HREF="kernel_resources-2.html" REL=next>
8 <LINK HREF="kernel_resources.html#toc1" REL=contents>
11 <A HREF="kernel_resources-2.html">Next</A>
13 <A HREF="kernel_resources.html#toc1">Contents</A>
15 <H2><A NAME="s1">1. Trace and debug Utilities</A></H2>
17 <P>During the development process, an execution log is useful to
18 identify problems. This log contains messages, variables values,
19 source files names and line numbers. It is recommended to verify
20 assertions on variables values and if necessary, to stop the execution
21 at debug time, in order to validate all parts of code.
22 <H2><A NAME="ss1.1">1.1 Two modes: debug and release</A>
25 <P>The goal of debug mode is to check as many features as possible
26 during the early stages of the development process. The purpose of
27 the utilities provided in SALOME is to help the developer to add
28 detailed traces and check variables values, without writing a lot
30 <P>When the code is assumed to be valid, the release mode optimizes
31 execution, in terms of speed, memory, and display only user level
33 <P>But, some informations must always be displayed in both modes:
34 especially messages concerning environment or internal errors, with
35 version identification. When an end user is confronted to such a
36 message, he may refer to a configuration documentation or send the
37 message to the people in charge of SALOME installation, or to the
38 development team, following the kind of error.
39 <H2><A NAME="ss1.2">1.2 C++ Macros for trace and debug</A>
42 <P>SALOME provides C++ macros for trace and debug. These macros
43 are in <CODE>SALOME/src/utils/utilities.h</CODE> and this file must be included
44 in C++ source. Some macros are activated only in debug mode, others
45 are always activated. To activate the debug mode, <CODE>_DEBUG_</CODE> must be
46 defined, which is the case when SALOME Makefiles are generated from
47 configure, without options. When <CODE>_DEBUG_</CODE> is undefined (release mode),
48 the debug mode macros are defined empty (they do nothing). So, when
49 switching from debug to release, it is possible (and recommended)
50 to let the macro calls unchanged in the source.
51 <P>All the macros writing on the standard output start by flushing
52 the standard error. At the end of the display those macros flush
54 <P>Two informations are systematically added in front of the information
58 <LI>the name of the source file in which the macros is set;</LI>
59 <LI>the line number of the source file at which the macro is set.</LI>
61 <H3>Macros defined in debug and release modes</H3>
63 <H3>INFOS_COMPILATION</H3>
65 <P>The C++ macro <CODE>INFOS_COMPILATION</CODE> writes on the standard output
66 informations about the compiling process:
69 <LI>the name of the compiler : <CODE>g++, KCC, CC, pgCC</CODE>;</LI>
70 <LI>the date and the time of the compiling processing process.</LI>
72 <P>This macro <CODE>INFOS_COMPILATION</CODE> does not have any argument. Moreover,
73 it is defined in both compiling mode : <CODE>_DEBUG_</CODE> and <CODE>_RELEASE_</CODE>.
77 #include "utilities.h"
78 int main(int argc , char **argv)
86 <P>In both compiling mode <CODE>_DEBUG_</CODE> and <CODE>_RELEASE_</CODE>, The C++ macro <CODE>INFOS</CODE>
87 writes on the standard output the string which has been passed in
92 #include "utilities.h"
93 int main(int argc , char **argv)
96 INFOS("NORMAL END OF THE PROCESS");
103 main.cxx [5] : NORMAL END OF THE PROCESS
105 <H3>Macros defined only in debug mode</H3>
107 <H3>MESSAGE(str)</H3>
109 <P>In <CODE>_DEBUG_</CODE> compiling mode only, the C++ macro <CODE>MESSAGE</CODE> writes
110 on the standard output the string which has been passed in argument
111 by the user. In <CODE>_RELEASE_</CODE> compiling mode, this macro is blank.
115 #include "utilities.h"
116 #include <string>
118 int main(int argc , char **argv)
121 const char *str = "Salome";
124 st = "Aster";
125 MESSAGE(c_str(st+" and CASTEM"));
132 - Trace main.cxx [8] : Salome
133 - Trace main.cxx [12] : Aster and CASTEM
135 <H3>BEGIN_OF(func_name)</H3>
137 <P>In <CODE>_DEBUG_</CODE> compiling mode, The C++ macro <CODE>BEGIN_OF</CODE> appends the
138 string <CODE>"Begin of "</CODE> to the one passed in argument by the
139 user and displays the result on the standard output. In <CODE>_RELEASE_</CODE>
140 compiling mode, this macro is blank.
144 #include "utilities.h"
145 int main(int argc , char **argv)
154 - Trace main.cxx [3] : Begin of a.out
156 <H3>END_OF(func_name)</H3>
158 <P>In <CODE>_DEBUG_</CODE> compiling mode, The C++ macro <CODE>END_OF</CODE> appends the string
159 <CODE>"Normal end of "</CODE> to the one passed in argument by the user
160 and displays the result on the standard output. In <CODE>_RELEASE_</CODE> compiling
161 mode, this macro is blank.
165 #include "utilities.h"
166 int main(int argc , char **argv)
175 - Trace main.cxx [4] : Normal end of a.out
179 <P>In <CODE>_DEBUG_</CODE> compiling mode, The C++ macro <CODE>SCRUTE</CODE> displays its
180 argument which is an application variable followed by the value of
181 the variable. In <CODE>_RELEASE_</CODE> compiling mode, this macro is blank.
185 #include "utilities.h"
186 int main(int argc , char **argv)
189 if( i > 0 ) SCRUTE(i) ; i=i+1;
196 - Trace main.cxx [5] : i=999
198 <H3>ASSERT(condition)</H3>
200 <P>In <CODE>_DEBUG_</CODE> compiling mode only, The C++ macro <CODE>ASSERT</CODE> checks the
201 expression passed in argument to be not NULL. If it is NULL the process
202 is stopped and the condition is written on the standard output. In
203 <CODE>_RELEASE_</CODE> compiling mode, this macro is blank. N.B. : if <CODE>ASSERT</CODE> is
204 already defined, this macro is ignored.
208 #include "utilities.h"
210 const char *ptrS = fonc();
212 cout << strlen(ptrS);
217 cout << table[k];
220 <A HREF="kernel_resources-2.html">Next</A>
222 <A HREF="kernel_resources.html#toc1">Contents</A>