/*!
-\page kernel_resources SALOME Kernel resources for developer
+\page kernel_resources Salome Kernel resources for developer
-<b>WORK in PROGRESS, INCOMPLETE DOCUMENT</b>
-\section S1_kernel_res Abstract
-
This document describes the development environment for
C++ and Python. Makefiles generation and usage are
introduced in another document: "using the %SALOME
execution at debug time, in order to validate all parts
of code.
-<ol>
-<li>
-<b>Two modes: debug and release</b>
+\subsection subsection21 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
optimizes execution, in terms of speed, memory, and
display only user level messages.
-But, some informations must always be displayed in both
+But, some information 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.
-</li>
-<li>
-<b>C++ Macros for trace and debug</b>
+
+\subsection subsection22 C++ Macros for trace and debug
%SALOME provides C++ macros for trace and debug. These
macros are in:
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_``
+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:
-``configure --disable-debug --enable-production``), the
+Makefiles are generated from CMake build system, without
+options. When _DEBUG_ is undefined (release mode:
+cmake -DCMAKE_BUILD_TYPE=Release ../KERNEL_SRC), 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
standard output, a file, or send them via CORBA, in
case of a multi machine configuration.
-Three informations are systematically added in front of
+Three information are systematically added in front of
the information displayed:
-
- the %thread number from which the message come from;
-
- 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.
-<ol>
-<li>
-<b>Macros defined in debug and release modes</b>
-\n
-<b>INFOS_COMPILATION</b>
+\subsection subsection23 Macros defined in debug and release modes
+- <b>INFOS_COMPILATION</b>\n
The C++ macro INFOS_COMPILATION writes on the trace
- buffer pool informations about the compiling process:
-
+ buffer pool information 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_.
-
+ mode : _DEBUG_ and _RELEASE_.\n
Example:
-
\code
#include "utilities.h"
int main(int argc , char **argv)
INFOS_COMPILATION;
...
}
-INFOS(str)
\endcode
-\n
-<b>INFOS</b>
+- <b>INFOS</b>\n
In both compiling mode _DEBUG_ and _RELEASE_, The C++
macro INFOS writes on the trace buffer pool %the string
- which has been passed in argument by the user.
-
+ which has been passed in argument by the user.\n
Example:
-
\code
#include "utilities.h"
int main(int argc , char **argv)
return 0;
}
\endcode
-
Displays:
-
\code
main.cxx [5] : NORMAL END OF THE PROCESS
\endcode
-\n
-<b>INTERRUPTION(str)</b>
+- <b>INTERRUPTION(str)</b>\n
In both compiling mode _DEBUG_ and _RELEASE_, The C++
macro INTERRUPTION writes on the trace buffer pool the
%string, with a special ABORT type. When the %thread in
charge of collecting messages finds this message, it
terminates the application, after message treatment.
-<b>IMMEDIATE_ABORT(str)</b>
-
+- <b>IMMEDIATE_ABORT(str)</b>\n
In both compiling mode _DEBUG_ and _RELEASE_, The C++
macro IMMEDIATE_ABORT writes the message str immediately on
standard error and exits the application. Remaining
messages not treated by the message collector %thread
are lost.
-</li>
-<li>
-<b>Macros defined only in debug mode</b>
-\n
-<b>MESSAGE(str)</b>
+\subsection subsection24 Macros defined only in debug mode
+- <b>MESSAGE(str)</b>\n
In _DEBUG_ compiling mode only, the C++ macro MESSAGE
writes on the trace buffer pool the %string which has
been passed in argument by the user. In _RELEASE_
- compiling mode, this macro is blank.
-
+ compiling mode, this macro is blank.\n
Example:
-
\code
#include "utilities.h"
#include <string>
}
\endcode
-
Displays:
-
\code
- Trace main.cxx [8] : Salome
- Trace main.cxx [12] : Aster and CASTEM
\endcode
-\n
-<b>BEGIN_OF(func_name)</b>
-
+- <b>BEGIN_OF(func_name)</b>\n
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
trace buffer pool. In _RELEASE_ compiling mode, this
- macro is blank.
-
+ macro is blank.\n
Example:
-
\code
#include "utilities.h"
int main(int argc , char **argv)
return 0;
}
\endcode
-
Displays:
-
\code
- Trace main.cxx [3] : Begin of a.out
\endcode
-\n
-<b>END_OF(func_name)</b>
+- <b>END_OF(func_name)</b>\n
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
trace buffer pool. In _RELEASE_ compiling mode, this
- macro is blank.
-
+ macro is blank.\n
Example:
-
\code
#include "utilities.h"
int main(int argc , char **argv)
return 0;
}
\endcode
-
Displays:
-
\code
- Trace main.cxx [4] : Normal end of a.out
\endcode
-\n
-<b>SCRUTE(var)</b>
+- <b>SCRUTE(var)</b>\n
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.
-
+ compiling mode, this macro is blank.\n
Example:
-
\code
#include "utilities.h"
int main(int argc , char **argv)
return 0;
}
\endcode
-
Displays:
-
\code
- Trace main.cxx [5] : i=999
\endcode
-\n
-<b>ASSERT(condition)</b>
+- <b>ASSERT(condition)</b>\n
In _DEBUG_ compiling mode only, The C++ macro ASSERT
checks the expression passed in argument to be not
NULL. If it is NULL the condition is written with the
macro INTERRUPTION (see above). The process exits after
trace of this last message. In _RELEASE_ compiling
mode, this macro is blank. N.B. : if ASSERT is already
- defined, this macro is ignored.
-
+ defined, this macro is ignored.\n
Example:
-
\code
#include "utilities.h"
...
cout << table[k];
\endcode
-</li>
-</ol>
-</li>
-</ol>
-
\section S3_kernel_res Exceptions
-<ol>
-<li>
-<b>C++ exceptions: class SALOME_Exception</b>
+\subsection subsection31 C++ exceptions: class SALOME_Exception
-<ol>
-<li>
-<b>definition</b>
+\subsubsection subsubsection311 Definition
The class SALOME_Exception provides a generic method to
send a message, with optional source file name and line
The class SALOME_Exception inherits its behavior from
the STL class exception.
-</li>
-<li>
-<b>usage</b>
+
+\subsubsection subsubsection312 Usage
The header %SALOME/src/utils/utils_SALOME_Exception.hxx
must be included in the C++ source, when raised or trapped:
\endcode
where LOCALIZED is a macro provided with
-``utils_SALOME_Exception.hxx`` which gives file name and
+utils_SALOME_Exception.hxx which gives file name and
line number.
The exception is handled like this:
The what() method overrides the one defined in the STL
exception class.
-</li>
-</ol>
-</li>
-<li>
-<b>CORBA exceptions</b>
-<ol>
-<li>
-<b>definition</b>
+\subsection subsection32 CORBA exceptions
+
+\subsubsection subsubsection321 Definition
The idl SALOME_Exception provides a generic CORBA
exception for %SALOME, with an attribute that gives an
packages used within %SALOME, such as OmniORB
exceptions, must be handled separately.
-</li>
-<li>
-<b>usage</b>
-<ol>
-<li>
+\subsubsection subsubsection322 Usage
<b>CORBA servant, C++</b>
The CORBA Server header for SALOME_Exception and a
macro to throw the exception are provided with the
- header ``KERNEL_SRC/src/Utils/Utils_CorbaException.hxx``:
+ header KERNEL_SRC/src/Utils/Utils_CorbaException.hxx:
\code
#include "Utils_CorbaException.hxx"
SALOME::BAD_PARAM);
\endcode
-</li>
-<li>
-<b>CORBA Client, GUI Qt C++</b>
-
- <b>NO MORE AVAILABLE in %SALOME 3.x</b>
+<b>CORBA Client, GUI Qt C++ (NO MORE AVAILABLE in %SALOME 3.x and later)</b>
The CORBA Client header for SALOME_Exception and a Qt
function header that displays a message box are
provided in:
- ``KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx``
+ KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
\code
#include "SALOMEGUI_QtCatchCorbaException.hxx"
}
\endcode
-</li>
-<li>
<b>CORBA Client, C++, without GUI</b>
Nothing specific has been provided to the developer
SALOMEGUI_QtCatchCorbaException.hxx to see how to get
the information given by the exception %object.
-</li>
-</ol>
-</li>
-</ol>
-</ol>
-
\section S4_kernel_res Miscellaneous tools
-<ol>
-<li>
-<b>Singleton</b>
-<ol>
-<li>
-<b>Definition</b>
+\subsection subsection41 Singleton
+\subsubsection subsubsection411 Definition
%A singleton is an application data which is created and
deleted only once at the end of the application
static singleton data before the first executable
statement. They are deleted after the last statement execution.
-The ``SINGLETON_`` template class deals with dynamic
+The SINGLETON_ template class deals with dynamic
singleton. It is useful for functor objects. For
example, an %object that connects the application to a
system at creation and disconnects the application at deletion.
-</li>
-<li>
-<b>Usage</b>
+\subsubsection subsubsection412 Usage
To create a single instance of a POINT %object:
assert(p1==p2)
\endcode
-</li>
-<li>
-<b>Design description</b>
+\subsubsection subsubsection413 Design description
Here are the principles features of the singleton
design:
-
- the user creates an %object of class TYPE by using the
- class method ``SINGLETON_<TYPE>::Instance()`` which
+ class method SINGLETON_<TYPE>::Instance() which
returns a pointer to the single %object ;
-
-- to create an %object, ``SINGLETON_<TYPE>::Instance()``
+- to create an %object, SINGLETON_<TYPE>::Instance()
uses the default constructor of class TYPE ;
-
- at the same time, this class method creates a
destructor %object which is added to the generic list
of destructor objects to be executed at the end of
the application (atexit) ;
-
- at the end of the application process all the
- deletions are performed by the ``Nettoyage()`` C function
+ deletions are performed by the Nettoyage() C function
which executes the destruction objects end then
deletes the destructions objects themselves ;
+- the Nettoyage() C function using atexit() C function
+ is embedded in a static single %object ATEXIT_().
-- the ``Nettoyage()`` C function using ``atexit()`` C function
- is embedded in a static single %object ``ATEXIT_()``.
-
-</li>
-</ol>
-</li>
-</ol>
*/
