doc/KernelResources/kernel_resources-1.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   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>
   7
   8  <LINK HREF="kernel_resources.html#toc1" REL=contents>
   9 </HEAD>
  10 <BODY>
  11 <A HREF="kernel_resources-2.html">Next</A>
  12 Previous
  13 <A HREF="kernel_resources.html#toc1">Contents</A>
  14 <HR>
  15 <H2><A NAME="s1">1. Trace and debug Utilities</A></H2>
  16
  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>
  23 </H2>
  24
  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
  29 of code.
  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
  32 messages.
  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>
  40 </H2>
  41
  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
  53 the standard output.
  54 <P>Two informations are systematically added in front of the information
  55 displayed:
  56 <P>
  57 <UL>
  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>
  60 </UL>
  61 <H3>Macros defined in debug and release modes</H3>
  62
  63 <H3>INFOS_COMPILATION</H3>
  64
  65 <P>The C++ macro <CODE>INFOS_COMPILATION</CODE> writes on the standard output
  66 informations about the compiling process:
  67 <P>
  68 <UL>
  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>
  71 </UL>
  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>.
  74 <P>Example :
  75 <P>
  76 <PRE>
  77 #include &quot;utilities.h&quot;
  78 int main(int argc , char **argv)
  79 {
  80   INFOS_COMPILATION;
  81   ...
  82 }
  83 </PRE>
  84 <H3>INFOS(str)</H3>
  85
  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
  88 argument by the user.
  89 <P>Example :
  90 <P>
  91 <PRE>
  92 #include &quot;utilities.h&quot;
  93 int main(int argc , char **argv)
  94 {
  95   ...
  96   INFOS(&quot;NORMAL END OF THE PROCESS&quot;);
  97   return 0;
  98 }
  99 </PRE>
 100 <P>displays :
 101 <P>
 102 <PRE>
 103 main.cxx [5] : NORMAL END OF THE PROCESS
 104 </PRE>
 105 <H3>Macros defined only in debug mode</H3>
 106
 107 <H3>MESSAGE(str)</H3>
 108
 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.
 112 <P>Example :
 113 <P>
 114 <PRE>
 115 #include &quot;utilities.h&quot;
 116 #include &lt;string&gt;
 117 using namespace std;
 118 int main(int argc , char **argv)
 119 {
 120   ...
 121   const char *str = &quot;Salome&quot;;
 122   MESSAGE(str);
 123   ... const string st;
 124   st = &quot;Aster&quot;;
 125   MESSAGE(c_str(st+&quot; and CASTEM&quot;));
 126   return 0;
 127 }
 128 </PRE>
 129 <P>displays :
 130 <P>
 131 <PRE>
 132 - Trace main.cxx [8] : Salome
 133 - Trace main.cxx [12] : Aster and CASTEM
 134 </PRE>
 135 <H3>BEGIN_OF(func_name)</H3>
 136
 137 <P>In <CODE>_DEBUG_</CODE> compiling mode, The C++ macro <CODE>BEGIN_OF</CODE> appends the
 138 string <CODE>&quot;Begin of &quot;</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.
 141 <P>Example :
 142 <P>
 143 <PRE>
 144 #include &quot;utilities.h&quot;
 145 int main(int argc , char **argv)
 146 {
 147   BEGIN_OF(argv[0]);
 148   return 0;
 149 }
 150 </PRE>
 151 <P>displays :
 152 <P>
 153 <PRE>
 154 - Trace main.cxx [3] : Begin of a.out
 155 </PRE>
 156 <H3>END_OF(func_name)</H3>
 157
 158 <P>In <CODE>_DEBUG_</CODE> compiling mode, The C++ macro <CODE>END_OF</CODE> appends the string
 159 <CODE>&quot;Normal end of &quot;</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.
 162 <P>Example :
 163 <P>
 164 <PRE>
 165 #include &quot;utilities.h&quot;
 166 int main(int argc , char **argv)
 167 {
 168   END_OF(argv[0]);
 169   return 0;
 170 }
 171 </PRE>
 172 <P>displays :
 173 <P>
 174 <PRE>
 175 - Trace main.cxx [4] : Normal end of a.out
 176 </PRE>
 177 <H3>SCRUTE(var)</H3>
 178
 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.
 182 <P>Example :
 183 <P>
 184 <PRE>
 185 #include &quot;utilities.h&quot;
 186 int main(int argc , char **argv)
 187 {
 188   const int i=999;
 189   if( i &gt; 0 ) SCRUTE(i) ; i=i+1;
 190   return 0;
 191 }
 192 </PRE>
 193 <P>displays :
 194 <P>
 195 <PRE>
 196 - Trace main.cxx [5] : i=999
 197 </PRE>
 198 <H3>ASSERT(condition)</H3>
 199
 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.
 205 <P>Example :
 206 <P>
 207 <PRE>
 208 #include &quot;utilities.h&quot;
 209 ...
 210 const char *ptrS = fonc();
 211 ASSERT(ptrS!=NULL);
 212 cout &lt;&lt; strlen(ptrS);
 213 float table[10];
 214 int k;
 215 ...
 216 ASSERT(k&lt;10);
 217 cout &lt;&lt; table[k];
 218 </PRE>
 219 <HR>
 220 <A HREF="kernel_resources-2.html">Next</A>
 221 Previous
 222 <A HREF="kernel_resources.html#toc1">Contents</A>
 223 </BODY>
 224 </HTML>