DCQ: prepare V2.0.0

[modules/kernel.git] / doc / DevelopersGuide / DevelopersGuide.tex.in

\documentclass[11pt,a4paper]{article}
\usepackage{isolatin1}
\usepackage{psfig}
\usepackage{graphicx}
\usepackage{fancyheadings}
\usepackage{lastpage}
\usepackage{epic}
\usepackage{longtable}
\usepackage{times}
\usepackage{verbatim}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% mise en page du document %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \voffset -20pt
  \topmargin 0 cm
  \headheight 15pt
  \headsep 0 cm
  \textheight 670 pt
  \footskip 1 cm
  \marginparwidth 0 cm
  \oddsidemargin 0 cm
  \evensidemargin 0 cm
  \textwidth 16.2 cm
  \parindent 0 cm

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test si on passe par pdflatex %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newif\ifpdf 
        \ifx\pdfoutput\undefined 
        \pdffalse % we are not running pdflatex 
        \else 
        \pdfoutput=1 % we are running pdflatex 
        \pdfcompresslevel=9     % compression level for text and image;
        \pdftrue 
        \fi

\ifpdf
\usepackage{thumbpdf}
\usepackage[pdftex,
        colorlinks=true,
        urlcolor=rltblue,       % \href{...}{...} external (URL)
        filecolor=rltgreen,     % \href{...} local file
        linkcolor=rltred,       % \ref{...} and \pageref{...}
        pdftitle={Adding a new module or unit development},
        pdfauthor={Patrick Goldbronn, Marc Tajchman},
        pdfsubject={},
        pdfkeywords={},
        pagebackref,
        pdfpagemode=None,
        bookmarksopen=true]{hyperref}
\usepackage{color}
\definecolor{rltred}{rgb}{0.75,0,0}
\definecolor{rltgreen}{rgb}{0,0.5,0}
\definecolor{rltblue}{rgb}{0,0,0.75}
\else
\usepackage{color}
\fi

%%
%%%%%%%%%%%%%%%%%%%%%%%%%
%% epaisseur des traits %
%%%%%%%%%%%%%%%%%%%%%%%%%
\linethickness{1pt}
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% mise en page des environnement array %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \arraycolsep 2pt
 \renewcommand{\arraystretch}{1.6}
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% interligne du document %
%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\baselinestretch}{1.2}
%%
%%%%%%%%%%%%%%%%%%%%%%%%
%% haut et bas de page %
%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand{\version}{0.3}

\pagestyle{fancy}
%
 \chead{}
 \lhead{}
 \rhead{}
%
 \lfoot{
        SALOME
       }
 \cfoot{
         Using the SALOME configuration and building system V. \version
       }
 \rfoot{
        \thepage/\pageref{LastPage}
       }
%%
 \setlength{\headrulewidth}{0pt}
 \setlength{\footrulewidth}{1pt}
%
%-----------------------------------------------------------
% Les racourcis :
\newcommand{\fsc}{\sc}


%%-----------------------------------------------------------
%%-----------------------------------------------------------
%%-----------------------------------------------------------


%% Bring items closer together in list environments
% Prevent infinite loops
\let\Itemize =\itemize
\let\Enumerate =\enumerate
\let\Description =\description
% Zero the vertical spacing parameters
\def\Nospacing{\itemsep=4pt\topsep=-5pt\partopsep=-5pt%
\parskip=0pt\parsep=0pt}
% Redefinition de art12.sty pour commencer a la marge de gauche
%\leftmargini 1.2em      % 2.5em

\def\noitemsep{
% Redefine the environments in terms of the original values
\renewenvironment{itemize}{\Itemize\Nospacing}{\endlist}
\renewenvironment{enumerate}{\Enumerate\Nospacing}{\endlist}
\renewenvironment{description}{\Description\Nospacing}%
{\endlist}
}

\def\doitemsep{
% Redefine the environments to the original values
\renewenvironment{itemize}{\Itemize}{\endlist}
\renewenvironment{enumerate}{\Enumerate}{\endlist}
\renewenvironment{description}{\Description}{\endlist}
}

%%%% fin macro %%%%

\begin{document}
\noitemsep

%%%%%%%%%%%%%%%%%%%%
%% TITRE AUTEUR(S) %
%%%%%%%%%%%%%%%%%%%%

\textcolor{white}{.}
\vfill\vfill
\begin{figure}[!h]
\begin{center}
\ifpdf
        \includegraphics[width=11.88cm, height=5.11cm]{@srcdir@/SALOME.png}
\else
        \includegraphics[width=11.88cm, height=5.11cm]{@srcdir@/SALOME.ps}
\fi
\end{center}
\end{figure}

\bigskip
\bigskip

\begin{center}
{\usefont{T1}{phv}{bx}{n}
\huge Using the SALOME configuration and building system
environment
}
\bigskip
\medskip

{\LARGE Version \version}
\end{center}

\vfill

{
\large
\renewcommand{\arraystretch}{0.85}
\begin{tabular}{lll}
Patrick & Goldbronn & C.E.A. \\
Marc & Tajchman & C.E.A.
\end{tabular}
}


\def\Mkin{{\tt Makefile.in }}

\thispagestyle{empty}

\newpage
%-----------------------------------------------------------
\section*{Successive versions}

\vfill
\begin{tabular}{|p{2cm}|p{1.5cm}|p{8cm}|p{2cm}|}
\hline
\textbf{Date} & \textbf{Version} & \textbf{Description} & \textbf{Author(s)}\\
\hline
10/07/2001& 0.0 & Initial version & PG \\
\hline
25/07/2001 & 0.1 & English traduction, rewriting & MT \\
\hline
29/08/2001 & 0.2 & Add source creation, some precision & PG \\
\hline
24/05/2002 & 0.3 & Add instruction to do installation correctly & PG \\
\hline
\end{tabular}
\vfill
\vfill

%\thispagestyle{empty}
\newpage
%-----------------------------------------------------------
  \begin{abstract}
    This document contains rules and advices to configure,
    build and extend the SALOME platform.
  \end{abstract}

  \newpage
%-----------------------------------------------------------
  \tableofcontents
  \newpage
  \parskip 0.2 cm
%-----------------------------------------------------------
\newpage

\section{SALOME Configuration}

\subsection{Directories organisation}

We suppose here that you unpack the SALOME distribution from scratch.
The path to the SALOME sources will be named ``top source directory''
or {\tt SALOME\_ROOT}.

It is possible, but not advised, to build the set of binaries and libraries
in the same subtree. Instead, we suppose you have choosen a different subtree
where to put builded files (you can so build to multiples architectures from the same source tree). The root of the build subtree will be named
``top build directory''.

At the end of configuration and compilation processs, you may install
builded files in a separate subtree, name ``installation subtree''.
The root of the installation subtree will be named ``top installation directory''.

The figure \ref{FigDirs} shows subtrees organisation.

\begin{figure}[h]
\ifpdf
        \includegraphics{@srcdir@/subtrees.pdf}
\else
        \includegraphics{@srcdir@/subtrees.eps}
\fi
\caption{\label{FigDirs} Subtrees organisation}
\end{figure}

\subsection{PreConfiguration step}

SALOME needs some environment variables (to be defined for example in
a .cshrc or .bashrc file in your home directory)~:

\begin{tabular}{|p{3.5cm}|p{11cm}|}
\hline
\it variable & \it set value and check \\
\hline
{\tt QTDIR} & root directory of qt distribution ({\tt \$QTDIR/lib} must contain libqt.so) \\ 
\hline
{\tt HDF5HOME} & root directory of hdf5 distribution ({\tt \$HDF5HOME/lib} must contain libhdf5.so) \\
\hline
{\tt VTKHOME} & root directory of vtk distribution ({\tt \$VTKHOME/common} must contain libVTKCommon.so) \\
\hline
{\tt CASROOT} & root directory of OpenCascade distribution ({\tt \$CASROOT/Linux/lib} must contain libTKernel.so) \\
\hline
{\tt PYTHONHOME} & root directory of python distribution ({\tt \$PYTHONHOME/lib/pythonXXX/config} must contain libpythonXXX.a) \\
\hline
{\tt OMNIORB\_CONFIG } & path to the omniORB.cfg file (this file contains default
options to omniORB, see below) \\
\hline
\end{tabular}

\bigskip
Create a file named omniORB.cfg in your root tree, containing default
options to omniORB. Put in this file, the following line~:
\begin{verbatim}
ORBInitRef NameService=corbaname::localhost
\end{verbatim}

(tells omniORB that the CORBA name service is local).

\subsection{Configuration step}

\begin{enumerate}
\item There are two cases~:
\begin{itemize}
\item There is a {\tt configure} file in the top source directory,
and you didn't change the SALOME structure (adding a module or unit,
see sections \ref{sec_module} or \ref{sec_unit} below).
Go to point \ref{pConf}.
\item You don't have a {\tt configure} file or you add a module/unit
in the SALOME system.
Go to point \ref{pReConf}
\end{itemize}

\item \label{pReConf}
Go to the top source directory and type~:
\begin{verbatim}
./reconfigure
\end{verbatim}
This script find all file with suffix {\tt .in} (which will be generate by {\tt configure} script) and add them in {\tt configure.in} file, launch {\tt aclocal} and {\tt autoconf} to generete {\tt configure} script.

Continue with point \ref{pConf}

\item \label{pConf}
Go to the top build directory you choose.

If you plan to install SALOME files after building in a non-standard
location (i.e. different from /usr/local), type~:

\begin{verbatim}
<path to the top source directory>/configure \
                  --prefix=<installation directory>
\end{verbatim}

otherwise, type~:
\begin{verbatim}
<path to the top source directory>/configure
\end{verbatim}

where ``path to the top source directory'' is to be replaced by the path
to the SALOME sources.

For other options to the configure command, type~:
\begin{verbatim}
<path to the top source directory>/configure --help
\end{verbatim}

This will create a mirror subtree of the sources into the top build directory
where object files, binaries and libraries will be builded. Also a makefile
system will be created into the build tree.

\end{enumerate}

\subsection{PostConfiguration step}

This phase is optional, to be used only if the compilation process
(see next section) fails to use {\tt libtool} script.

On some systems, the {\tt libtool} script generated by the configure
command will not operate correctly during compilation
(see next section). If you encounter this situation,
copy the local libtool script in your system (e.g. in the /usr/bin
directory) to the top build directory after configuration and before
compilation phases.

Check the following line in libtool script :
\begin{verbatim}
deplibs_check_method=...
\end{verbatim}

If needed, replace this line by
\begin{verbatim}
deplibs_check_method="pass_all"
\end{verbatim}

\section{SALOME compilation}

From the top build directory, type
\begin{verbatim}
make
\end{verbatim}

After some time (be patient ...), it will create various binaries.
Building SALOME is split in several phases~:

\begin{itemize}
\item {\tt make inc} : copy/update header files exported by development units
in the directory {\tt inc} of the build tree ;
\item {\tt make depend\_idl} : determine dependencies between idl files (useful when recompiling SALOME after idl modification);
\item {\tt make depend (make dep)} : determine dependencies between source files and header files (useful when recompiling SALOME after source modification);
\item {\tt make lib} : generate libraries, put a copy/link into the {\tt lib} directory of the build tree;
\item {\tt make bin} : generate binaries;
\item {\tt make tests (make check)} : build and run tests (not yet implemented).
\end{itemize}

After building, testing, the user may install the system in a choosen directory
(different from and not included in the top source directory and the top build directory).

From the top build directory, type~:
\begin{quotation}\noindent%
 {\tt make install} : install libraries, header and idl files, binaries,
resource files in the installation directory
\end{quotation}

\section{\label{sec_module}Module creation}

In this section, the new module will be named {\tt <Module>}. Replace
each occurence with the real name of your module.

\begin{enumerate}
\item In the source tree root {\tt SALOME\_ROOT}, create a new directory 
{\tt <Module>} :

\begin{verbatim}
cd SALOME_ROOT
mkdir <Module>
\end{verbatim}

\item Modify the \Mkin file in the {\tt SALOME\_ROOT} directory to add the new module~:

Append to the line beginning with
\begin{verbatim}
SUBDIRS = 
\end{verbatim}

the name of the new module.

\item In the module root directory, create two subdirectories {\tt src} and {\tt resources} and create a file \Mkin
 (e.g. copy the corresponding file in {\tt GEOM} module for example)~:

\begin{verbatim}
cd <Module>
mkdir src
mkdir resources
cp ../GEOM/Makefile.in .
\end{verbatim}

\item In the {\tt src} subdirectory, copy a \Mkin file (e.g. from the corresponding file in {\tt GEOM/src} subdirectory  for example)~:

\begin{verbatim}
cd src
cp ../../GEOM/src/Makefile.in .
\end{verbatim}

\item Edit this file and replace the line
\begin{verbatim}
MODULE = GEOM
\end{verbatim}

with
\begin{verbatim}
MODULE = <Module>
\end{verbatim}

\item Edit this file and replace the line
\begin{verbatim}
SUBDIRS = GEOMDS GEOM GEOMGUI
\end{verbatim}

with
\begin{verbatim}
SUBDIRS = 
\end{verbatim}

(empty list of development units in this module).

\item Edit this file and replace the line
\begin{verbatim}
RESOURCES_FILES = arc.png \
...
\end{verbatim}

with
\begin{verbatim}
RESOURCES_FILES = 
\end{verbatim}

(list of all ressources for this module).

\item Add the new \Mkin files in the global list of .in files.

In the root directory of the source tree, execute the {\tt reconfigure}
script or manually :

\begin{enumerate}
\item edit the configure.in file in the source tree root,
add \Mkin files into the {\tt AC\_OUTPUT} list,
\item from the source tree root directory, run the {\tt genconf} script which launch {\tt aclocal} and {\tt autoconf}.
\end{enumerate}

\end{enumerate}

Figure \ref{srctree_module} summarize these changes.

\begin{figure}[h]
\ifpdf
        \includegraphics{@srcdir@/srctree_module.pdf}
\else
        \includegraphics{@srcdir@/srctree_module.eps}
\fi
\caption{\label{srctree_module} Source tree : modification when adding an new module}

\end{figure}

\section{\label{sec_unit}Development unit creation}

Here we want to add a development unit named {\tt <Unit>}
in the existing module {\tt <Module>} (replace the names {\tt <Unit>}
and {\tt <Module>} with real ones).

\begin{enumerate}

\item In the {\tt src} subdirectory of {\tt <Module>}, create a 
subdirectory named {\tt <Unit>}~:

\begin{verbatim}
cd <path to <Module> >/src
mkdir <Unit> 
\end{verbatim}

Modify then \Mkin file in the {\tt src} directory to add 
the new unit
to the compilation process~:

Complete the line beginning with 
\begin{verbatim}
SUBDIRS = ... 
\end{verbatim}

with the name of the new directory

\begin{verbatim}
SUBDIRS = ... <Unit>
\end{verbatim}

\item Create a \Mkin file in the new {\tt <Unit>} directory (you can copy a \Mkin file from the corresponding subdirectory in {\tt GEOM} module : {\tt GEOM/src/GEOMGUI} subdirectory  for example, and modify as you need)


\begin{verbatim}
cd <Unit>
... create Makefile.in
\end{verbatim}

The details of \Mkin creation is detailed in the next section.
\end{enumerate}


The different files of your unit must be located in several directories
(see figure \ref{srctree_unit} and the list below).

\begin{figure}[!h]
\ifpdf
        \includegraphics{@srcdir@/srctree_unit.pdf}
\else
        \includegraphics{@srcdir@/srctree_unit.eps}
\fi
\caption{\label{srctree_unit}Source tree : modification when adding an new unit in an existing module}
\end{figure}

\begin{itemize}
\item Private source and header files of your unit

Place the only copy of these files in your unit. If you use
the proposed makefile system, dont put them in subdirectories
of your unit.

Note
\begin{quotation}\noindent%
Using a non-flat directory structure for an unit, has not been
tested but it should work. You must write your makefile to take care 
of subdirectories.
\end{quotation}

\item Exported idl files from a unit

These files are provided by the unit for CORBA communication
with other units.

Place the only copy of these files into the idl subdirectory of the
root source tree.

\item Exported header files from a unit

These files are provided by the unit for direct communication
from other units (using the unit's library).

Place the master copy of these files in your unit subtree.

Assure that these files are automatically or manually copied in
the inc subdirectory of the root build tree.

\end{itemize}

\section{Creating a \Mkin file in a new unit}

\subsection{Using predefined make rules}

Copy the following \Mkin \ skeleton in the unit directory~:

\verbatiminput{@srcdir@/makefile.skel}

Adapt this \Mkin skeleton to your particular needs~:
\begin{itemize}
\item if you have to compile a library

\begin{enumerate} 
\item Complete the line
\begin{verbatim}
LIB = 
\end{verbatim}

as
\begin{verbatim}
LIB = lib<MyLibrary>.la
\end{verbatim}

Example~:
\begin{verbatim}
LIB = libGeometryGui.la
\end{verbatim}

Notes
\begin{enumerate}
\item the library name {\bf must} begin with {\tt lib} and end with 
{\tt .la} (this allows automatic creation of shared libraries with libtool).
\item there must be only one library by development unit
\end{enumerate}

\item Also add to the line~:
\begin{verbatim}
LIB_SRC = 
\end{verbatim}
the list of sources files (in this unit) needed to build the library

\item If your library uses QT MOC file, add to the line~:
\begin{verbatim}
LIB_MOC =
\end{verbatim}
the list of headers files to transform with moc.

\item If your library uses CORBA functionnalities from other units (i.e.
uses idl files exported from other units), add to the line~:
\begin{verbatim}
LIB_CLIENT_IDL =
\end{verbatim}
the list of idl files.

\item If your unit provides CORBA functionnalities (i.e. exports idl
files to the other units), add to the line~:
\begin{verbatim}
LIB_SERVER_IDL =
\end{verbatim}
the list of idl files.
\end{enumerate}

\item if you want to build one or more executables~:

\begin{enumerate} 
\item Complete the line
\begin{verbatim}
BIN = 
\end{verbatim}

as
\begin{verbatim}
BIN = <MyBin1> <MyBin2> ..
.
\end{verbatim}

Note
\begin{quotation}\noindent%
For each executable in the {\tt BIN} list, say {\tt MyBin1}, the main 
function {\bf must} be in a file named accordingly, in this example~: 
{\tt MyBin1.cxx} and {\tt MyBin2.cxx}.
\end{quotation}

\item Also add to the line~:
\begin{verbatim}
BIN_SRC = 
\end{verbatim}
the list of source files (in this unit) needed to build {\bf all} the executables,
{\bf excluding files containing main function(s)}.

Notes~:
\begin{enumerate}
\item The makefile system will automatically add to each executable, its
main function file. That's why these files must not be included in the 
{\tt BIN\_SRC} list
\item The object files (compiled from the source files in the {\tt BIN\_SRC}
list) will be properly dispatched between the executables by the linker.
\end{enumerate}

\item If your binaries uses QT MOC file, add to the line~:
\begin{verbatim}
BIN_MOC =
\end{verbatim}
the list of headers files to transform with moc.

\item If your binaries uses CORBA functionnalities from other units (i.e.
uses idl files exported from other units), add to the line~:
\begin{verbatim}
BIN_CLIENT_IDL =
\end{verbatim}
the list of idl files.

\item If your unit provides CORBA functionnalities (i.e. exports idl
files to the other units), add to the line~:
\begin{verbatim}
BIN_SERVER_IDL = 
\end{verbatim}
the list of idl files.

\end{enumerate}

\item List the exported header files that your unit provides
to other developments units~:

Complete the line
\begin{verbatim}
EXPORT_HEADERS =
\end{verbatim}
with the list header files.

Note
\begin{quotation}\noindent%
The makefile system will automatically copy these files in a 
subdirectory {\tt inc} in the top build directory, and maintain
coherence with your private copy inside your unit subtree.
This is to assure name uniqueness of differents exported header
files from different units and to write easier makefiles. 
\end{quotation}

\item List the python scripts files that your unit export~:

Complete the line
\begin{verbatim}
EXPORT_PYSCRIPTS =
\end{verbatim}

\item To generate qm file from po file (use by QT), list po files in~:

\begin{verbatim}
PO_FILES =
\end{verbatim}
Note
\begin{quotation}\noindent%
The resulting qm files will ge generated directory which contain Makefile.
It will be copied in resources directory when do {\tt 'make install'}.
\end{quotation}

\end{itemize}


\subsection{Using your own makefiles in an unit}

If the proposed makefile system don't suit your needs (several libraries,
non flat unit subtree structure, ...). It's possible
to write your own makefiles.

\begin{enumerate}
\item Create a file \Mkin

This file must begin with the lines

\verbatiminput{@srcdir@/makefile_own.skel}

\bigskip

The rest of the file has the standard GNU make format.

You must define the following targets~:

\begin{enumerate}
\item {\tt inc} : copy/update the exported header files to the {\tt \$top\_builddir/inc} directory
\item {\tt dep} : update dependencies
\item {\tt lib} : build libraries and link them into the {\tt \$top\_builddir/lib} directory
\item {\tt bin} : build executables and link them into the {\tt \$top\_builddir/bin} directory
\end{enumerate}

Some of these targets may be empty, if not applicable.

\end{enumerate}

The line 
\begin{verbatim}
@\texttt{COMMENCE}@
\end{verbatim}
provides a number of predefined variables that you can use in your makefile
rules (defining standard libraries locations, compiler options, ..., see next section).


\section{Add or remove a script}

If you want to add a new shell script in {\tt SALOME\_ROOT/bin}, you must edit {\tt SALOME\_ROOT/Makefile.in} to add it in {\tt BIN\_SCRIPT}.

If this script have some package dependent variable, you must create a ".in" file and add this reference to {\tt configure.in} file.

To remove an existing script, you must of course remove it from CVS archive and also remove it from {\tt SALOME\_ROOT/Makefile.in} and if any, from {\tt configure.in}.

If you want to add a new python script, put it in {\tt EXPORT\_PYSCRIPTS} variable. It will be copied at same place than others executables.


\section{Add or remove an IDL file}

If you want to add a new IDL file in {\tt SALOME\_ROOT/idl}, you must edit {\tt SALOME\_ROOT/idl/Makefile.in} and add its in {\tt IDL\_FILES}.

To remove an existing IDL file, you must of course remove it from CVS archive and also remove it from {\tt SALOME\_ROOT/idl/Makefile.in}.


\section{Predefined symbols used in {\tt Makefile.in}}

You can use predefined symbols in you {\tt Makefile.in} files.
These symbols define
\begin{itemize}
\item compilation flags for source compiling,
\item header files location in your local system,
\item libraries needed for binaries linking.
\end{itemize}

For example to use the OpenCascade libraries in your unit, you will add the
\begin{itemize}
\item {\tt \$OCC\_INCLUDES} symbol to the included header file locations,
\item {\tt \$OCC\_CXXFLAGS} symbol to the compilation flags,
\item {\tt \$OCC\_LIBS} symbol to the linker's flags
\end{itemize}

If you use the predefined make rules, add the lines
\begin{verbatim}
CPPFLAGS+=$(OCC_INCLUDES)
CXXFLAGS+=$(OCC_CXXFLAGS)
LDFLAGS+=$(OCC_LIBS)
\end{verbatim}
in your {\tt Makefile.in} file after the @{\tt COMMENCE}@ line.

For each standard tool you need in SALOME (QT, python, OpenCascade, CORBA, VTK, \ldots), main symbols listed below.

\begin{enumerate}
\bigskip

\item {\it Corba}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt CORBA\_ROOT } & CORBA home base \\
\hline
{\tt CORBA\_INCLUDES} & compiler options to include CORBA headers \\ 
\hline
{\tt CORBA\_LIBS } & libraries needed to link with CORBA \\
\hline
{\tt CORBA\_CXXFLAGS } & C++ compiler options to use with CORBA \\ 
\hline
{\tt IDL} &  idl compiler \\
\hline
{\tt IDLCXXFLAGS} & options to the idl compiler to generate C++ 
stub or skeleton code \\ 
\hline
{\tt IDLPYFLAGS} &  options to the idl compiler to generate python
stub or skeleton code \\
\hline
{\tt IDL\_CLN\_H} & extension of generated CORBA header files (client side) \\
\hline
{\tt IDL\_CLN\_CXX} & extension of generated CORBA source files (client side) \\
\hline
{\tt IDL\_CLN\_OBJ} & extension of generated CORBA object files (client side) \\
\hline
{\tt IDL\_SRV\_H} & extension of generated CORBA header files (server side) \\
\hline
{\tt IDL\_SRV\_CXX} & extension of generated CORBA source files (server side) \\
\hline
{\tt IDL\_SRV\_OBJ} & extension of generated CORBA object files (server side) \\
\hline
\end{longtable}

\item {\it python}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt PYTHON} & python interpreter (absolute path to) \\
\hline
{\tt PYTHON\_VERSION} & python version \\
\hline
{\tt PYTHONHOME} & python home base (sometimes needed
                  to run python) \\
\hline
{\tt PYTHON\_INCLUDES} & compiler options to include python header files \\
\hline
{\tt PYTHON\_LIBS} & libraries needed to link with python \\
\hline
\end{longtable}

\bigskip
\item {\it QT}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt MOC} & moc compiler \\
\hline
{\tt UIC} & uic graphical compiler \\
\hline
{\tt QTDIR} & QT home base \\
\hline
{\tt QT\_ROOT} & QT home base \\
\hline
{\tt QT\_INCLUDES} & compiler options to include QT headers \\
\hline
{\tt QT\_MT\_INCLUDES} & same as above, for multithreaded applications \\
\hline
{\tt QT\_LIBS} & libraries needed to link with QT (single threaded) \\
\hline
{\tt QT\_MT\_LIBS} & same as above, for multithreaded applications \\
\hline
\end{longtable}

For SALOME developments, multithreaded versions of qt options and libraries
are needed.

\bigskip
\item {\it OpenGL}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt OGL\_INCLUDES} & compiler options to include OpenGL headers \\
\hline
{\tt OGL\_LIBS} & libraries needed to link with OpenGL  \\
\hline
\end{longtable}

\bigskip
\item {\it VTK}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt VTK\_INCLUDES} & compiler options to include VTK headers \\
\hline
{\tt VTK\_LIBS} & libraries needed to link with VTK  \\
\hline
\end{longtable}

\bigskip
\item {\it HDF (v5)}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt HDF5\_INCLUDES} & compiler options to include HDF headers \\
\hline
{\tt HDF5\_LIBS} & libraries needed to link with HDF  \\
\hline
{\tt HDF5\_MT\_LIBS} & libraries needed to link with HDF
  (multithreaded version)  \\
\hline
\end{longtable}

\bigskip
\item {\it OpenCascade}
\smallskip

\begin{longtable}{|p{3.2cm}|p{9.1cm}|}
\hline
\it variable & \it value \\
\hline
{\tt OCC\_INCLUDES} & compiler options to include OpenCascade headers \\
\hline
{\tt OCC\_LIBS} & libraries needed to link with OpenCascade  \\
\hline
{\tt OCC\_CXXFLAGS} & C++ compiler options to use with OpenCascade \\
\hline
\end{longtable}

\end{enumerate}

\section{Location of generated files in the build tree}

A partial view of the build tree shows the location of files generated
during the compilation process.

\begin{figure}[h]
\ifpdf
        \includegraphics{@srcdir@/bldtree.pdf}
\else
        \includegraphics{@srcdir@/bldtree.eps}
\fi
\caption{Partial view of the build tree : generated files during compilation}
\end{figure}

\section{What's matter when launch {\tt make install}}

When all libraries and binaries files are generated, make copies all identified files as {\tt configure} parameters {\tt --prefix}, {\tt bindir}, {\tt datadir}, ... (see {\tt configure --help} for details).

If you specify nothing, all are installed in {\tt <prefix>=/usr/local}.

All executables (binaries and scripts) are placed in {\tt <prefix>/bin} (see BIN and BIN\_SCRIPT variables in {\tt Makefile}).

All libraries are placed in {\tt <prefix>/lib} (see LIB variable in {\tt Makefile}).

All includes are placed in {\tt <prefix>/include} (see EXPORT\_HEADERS variable in {\tt Makefile}).

All idls are placed in {\tt <prefix>/idl} (see IDL\_FILES variable in {\tt Makefile}).

All python srcipts are placed in {\tt <prefix>/lib/pythonX.X/...} (see {\tt EXPORT\_PYSCRIPTS} variable in {\tt Makefile}).

All ressources files (icons, messages, configuration, ...) are placed in {\tt <prefix>/share/salome/ressources} (see RESOURCES\_FILES variable in {\tt Makefile}).


\section{Creating source files according to SALOME building system}

Building system use dependencies between files writing in Makefile rules. We use {\tt C} or {\tt C++} preprocessor to automatically generate this dependencies rules.

There are some configuration and useful macro defined in header file {\tt SALOMEconfig.h}. \textbf{All files should be included this header !}
You must include it ussing {\tt <>} delimiter because {\tt SALOMEconfig.h} must not appear in dependencies rules (see below \ref{include}). 

When a {\tt Makefile} is regenerate with {\tt config.status} script, all files are regenerates (in particular {\tt SALOMEconfig.h}).It is a restriction of {\tt autoconf 2.13} which could not regenerate only one particular file. 
So, all files which depend of {\tt SALOMEconfig.h} are rebuild even if it does not change. If you effectively change {\tt SALOMEconfig.h} file, you must clean all and rebuild.

\subsection{{\tt C} or {\tt C++} source files}

\textbf{You must name your {\tt C} file {\tt <myCFile>.c} and header file {\tt <myCHeaderFile>.h}}

\textbf{You must name your {\tt C++} file {\tt <myC++File>.cxx} and header file {\tt <myC++HeaderFile>.hxx}}

To have right dependencies rules, you must correctly write the include statement in your source files. We only take care about SALOME package header files to generate dependencies. We suppose that other header files (qt, vtk, OpenCascade, ...) are stables and are not modified when we build some SALOME modules.

According to cpp documentation, local header files must be included with {\tt ""} statement and system or tools headers files must be included with {\tt <>} statement.
\label{include}

If you do not respect this notation, dependencies would not be true and some rebuilding trouble can appear~ !

\subsection{idl files}

We use {\tt C} preprocessor to build dependencies between idl files. The same convention must be applied as {\tt C} or {\tt C++} source files. 

If included file is an external files, you must use statement {\tt <>} because this file will not be modified during SALOME devloppement and/or building. 
If included file is part of SALOME files, you must use statement {\tt ""}.

If you do not respect this notation, dependencies would not be true and some building or rebuilding trouble can appear~ !

\subsection{Included header file generated from idl file}

To include header file generated from idl file, you must use macro {\tt CORBA\_CLIENT\_HEADER} or \\
{\tt CORBA\_SERVER\_HEADER} defined in {\tt SALOMEconfig.h}.

These two macros replace idl prefix into corresponding header name generated (take care if you use client part or server part)

{\bf Example :}
\begin{verbatim}
#include  CORBA_CLIENT_HEADER(geom)
#include  CORBA_SERVER_HEADER(mesh)
\end{verbatim}


\end{document}