1. Trace and debug Utilities

During the development process, an execution log is useful to identify problems. This log contains messages, variables values, source files names and line numbers. It is recommended to verify assertions on variables values and if necessary, to stop the execution at debug time, in order to validate all parts of code.

1.1 Two modes: debug and release

The goal of debug mode is to check as many features as possible during the early stages of the development process. The purpose of the utilities provided in SALOME is to help the developer to add detailed traces and check variables values, without writing a lot of code.

When the code is assumed to be valid, the release mode optimizes execution, in terms of speed, memory, and display only user level messages.

But, some informations must always be displayed in both modes: especially messages concerning environment or internal errors, with version identification. When an end user is confronted to such a message, he may refer to a configuration documentation or send the message to the people in charge of SALOME installation, or to the development team, following the kind of error.

1.2 C++ Macros for trace and debug

SALOME provides C++ macros for trace and debug. These macros are in SALOME/src/utils/utilities.h and this file must be included in C++ source. Some macros are activated only in debug mode, others are always activated. To activate the debug mode, _DEBUG_ must be defined, which is the case when SALOME Makefiles are generated from configure, without options. When _DEBUG_ is undefined (release mode), the debug mode macros are defined empty (they do nothing). So, when switching from debug to release, it is possible (and recommended) to let the macro calls unchanged in the source.

All the macros writing on the standard output start by flushing the standard error. At the end of the display those macros flush the standard output.

Two informations are systematically added in front of the information displayed:

• the name of the source file in which the macros is set;
• the line number of the source file at which the macro is set.

Macros defined in debug and release modes

INFOS_COMPILATION

The C++ macro INFOS_COMPILATION writes on the standard output informations about the compiling process:

• the name of the compiler : g++, KCC, CC, pgCC;
• the date and the time of the compiling processing process.

This macro INFOS_COMPILATION does not have any argument. Moreover, it is defined in both compiling mode : _DEBUG_ and _RELEASE_.

Example :

#include "utilities.h"
int main(int argc , char **argv) 
{ 
  INFOS_COMPILATION;
  ...
}

INFOS(str)

In both compiling mode _DEBUG_ and _RELEASE_, The C++ macro INFOS writes on the standard output the string which has been passed in argument by the user.

Example :

#include "utilities.h"
int main(int argc , char **argv)
{ 
  ... 
  INFOS("NORMAL END OF THE PROCESS"); 
  return 0; 
}

displays :

main.cxx [5] : NORMAL END OF THE PROCESS

Macros defined only in debug mode

MESSAGE(str)

In _DEBUG_ compiling mode only, the C++ macro MESSAGE writes on the standard output the string which has been passed in argument by the user. In _RELEASE_ compiling mode, this macro is blank.

Example :

#include "utilities.h" 
#include <string> 
using namespace std; 
int main(int argc , char **argv) 
{ 
  ... 
  const char *str = "Salome";
  MESSAGE(str);
  ... const string st; 
  st = "Aster"; 
  MESSAGE(c_str(st+" and CASTEM")); 
  return 0;
}

displays :

- Trace main.cxx [8] : Salome
- Trace main.cxx [12] : Aster and CASTEM

BEGIN_OF(func_name)

In _DEBUG_ compiling mode, The C++ macro BEGIN_OF appends the string "Begin of " to the one passed in argument by the user and displays the result on the standard output. In _RELEASE_ compiling mode, this macro is blank.

Example :

#include "utilities.h" 
int main(int argc , char **argv) 
{ 
  BEGIN_OF(argv[0]);
  return 0;
}

displays :

- Trace main.cxx [3] : Begin of a.out

END_OF(func_name)

In _DEBUG_ compiling mode, The C++ macro END_OF appends the string "Normal end of " to the one passed in argument by the user and displays the result on the standard output. In _RELEASE_ compiling mode, this macro is blank.

Example :

#include "utilities.h" 
int main(int argc , char **argv) 
{ 
  END_OF(argv[0]);
  return 0; 
}

displays :

- Trace main.cxx [4] : Normal end of a.out

SCRUTE(var)

In _DEBUG_ compiling mode, The C++ macro SCRUTE displays its argument which is an application variable followed by the value of the variable. In _RELEASE_ compiling mode, this macro is blank.

Example :

#include "utilities.h"
int main(int argc , char **argv) 
{ 
  const int i=999;
  if( i > 0 ) SCRUTE(i) ; i=i+1;
  return 0;
}

displays :

- Trace main.cxx [5] : i=999

ASSERT(condition)

In _DEBUG_ compiling mode only, The C++ macro ASSERT checks the expression passed in argument to be not NULL. If it is NULL the process is stopped and the condition is written on the standard output. In _RELEASE_ compiling mode, this macro is blank. N.B. : if ASSERT is already defined, this macro is ignored.

Example :

#include "utilities.h" 
... 
const char *ptrS = fonc();
ASSERT(ptrS!=NULL); 
cout << strlen(ptrS); 
float table[10];
int k;
... 
ASSERT(k<10);
cout << table[k];