Join modifications from BR_Dev_For_4_0 tag V4_1_1.

[modules/gui.git] / doc / salome / gui / GUI / input / installing_salome.doc

/*!

\page installing_salome_page SALOME Installation Wizard Help

<hr>
<ul>
<li>\ref installing_products "Installing products with the Installation Wizard"
<ul>
<li>\ref gui_mode_install "GUI mode"
<li>\ref batch_mode_install "Batch mode"
<li>\ref environment_files "Environment files"
</ul>
<li>\ref notes_on_check "Notes on check products version procedure"
<li>\ref pick_up_env "Pick up the environment"
<li>\ref modifying_xml "Modifying XML configuration file"
<li>\ref installation_scripts "Implementing installation scripts for the new products"
<li>\ref finish_buttons "Customizing Readme page buttons"
</ul>
<hr>
\anchor installing_products 
<h1>Installing products with the <em>Installation Wizard</em></h1>

The Installation Wizard can be launched in two modes: \b GUI and \b
batch.
<br>The root directory of the Installation Wizard contains Python
script \b runInstall. To run the Installation Wizard just type \b runInstall.
in the terminal window:
<br><br>[ python ] \b runInstall [options]

Without options this script will launch the SALOME Installation
Wizard in the default mode (GUI). \n The default installation settings
can be overridden by using command line options. Each option has a
short and a long notation:

<b>-g / --gui</b>
\par
Runs the Installation Wizard in the GUI mode (this is the default
mode).

<b>-b / --batch</b>
\par
Runs the Installation Wizard in the terminal mode.

<b>-f FILE / --file=FILE</b>
\par
The XML configuration file to be used by the Installation Wizard.  If
this option is not used then the installation script tries to define
the \e Linux version and use the corresponding XML file if it exists. For
examle, for <em>Linux Mandrake 10.1</em>  the <b>config_Mandrake_10.1.xml</b>  file
will be used by default. If no appropriate file is found, the file
<b>config.xml</b> will be used. This file refers to the basic target platform 
which is <em>Linux Mandrake 10.1</em> for SALOME 3.0 and newer. If <b>config.xml</b>
file is not found either, a warning message box is shown (in GUI mode)
or printed to the console (in batch mode) and the Installation Wizard 
quits.

<b>-d DIR / --target=DIR</b>
\par
The target directory SALOME platform is to be installed to. 
If used, this option overrides the default target directory, given in
the configuration XML file (usually <b>${HOME}/salome_\<version\></b>, 
see \ref modifying_xml "here" for more details).

<b>-t DIR / --tmp=DIR</b>
\par
The directory, which should be used for temporary files. If given,
this option overrides the default temporary directory, given in the
configuration xml file (usually \b /tmp, see \ref modifying_xml "here"
for more information).

<b>-a / --all-from-sources</b>
\par
Forces all the products to be installed from sources (including all
SALOME modules). If this option is used, all default installation
modes for all products are ignored.
\n This option is helpful when the user wants to install SALOME on the
platform which is not officially supported. In this case, the user can
try to run the SALOME Installation Wizard with the \b -a option in order
to build all the products from sources.
\n <b>Note, that this is a time-consuming operation which can take
more than 24 hours depending on the computer.</b>

<b>-h / --help</b>
\par
Prints help information on the Installation Wizard's use.

<b>-v / --version</b>
\par
Prints version information (\b Note: this is the Installation Wizard's
version number, not the number of SALOME platform version).

The installation procedure supports different \em Linux platforms and
installs various installation 3d-party prerequisite products which are
required by SALOME platform. As it was mentioned above, the basic
target platform for SALOME 3.0 and newer is <em>Linux Mandrake 10.1</em>.
Use of configuration XML files gives a flexible way to modify the list
of products to be installed by the Installation Wizard without
changing the program source code. Just create your own XML
configuration file and implement installation scripts for the
prerequisite products you need and then use this XML file with the
Installation Wizard. This can be done, for example, for some Linux
platform which is not supported directly by the Installation
Wizard. See \ref modifying_xml "Modifying XML configuration file" and
\ref installation_scripts "Implementing installation scripts for the new products"
sections for more information.

<br>
\anchor gui_mode_install
<h2>GUI mode</h2>

The <b>Installation Wizard</b> GUI has been developed using
Trolltech's <b>Qt 3.0.5</b> toolkit. After launching the Installation
Wizard in the GUI mode the wizard window is shown to the user. This
wizard guides the user through several subsequent pages. To navigate
between the pages use \em "Next" and \em "Back" buttons in the lower
part of the wizard window. The \em "Cancel" button closes the wizard
window and quits the installation procedure after the user's
confirmation. The \em "Help" button opens an additional window to show
help information.

The first \em "Introduction" page is shown in \ref figure_1 "Figure 1". 
Skip this page by clicking \em "Next":

\anchor figure_1
\image html intropage.png 
\n <center><b>Figure 1:</b> "Introduction" page</center>

In the second page you are proposed to enter the target directory
where the SALOME platform should be installed to. You can also click
<em>"Browse..."</em> and choose the destination folder using the standard
browse directory dialog box.
\n If the directory you want to install products to does not exist you
are prompted to confirm directory creation. If you type a wrong
directory path, or if you do not have write permissions 
for the directory you use, the corresponding message box is shown.

You can also change the temporary directory (which is used to store
temporary files required for the installation).
\n In the bottom part of the window the total disk space required for
the installation and for the temporary files is displayed (see below
for more details).

In the GUI mode the Installation Wizard provides two different options
to install the SALOME platform: \b basic (default option) and
\b advanced. In the \b basic mode the user should enter the target
installation directory and temporary folder. All other installation
options are taken from the XML configuration file (see \ref figure_2 "Figure 2"):

\anchor figure_2
\image html productpage1.png
\n <center><b>Figure 2:</b> "Installation settings"</center>

In addition, you have a choice to use "Install all products from
sources" check box. If this option is turned on, all the products will
be installed from the sources (using their own build procedures). This
check box corresponds to the <b>--all-from-sources (-a)</b> option of
the \b runInstall script (see \ref installing_products "here").

\Note <b>Installation of all products from sources is a long-time
operation.</b>

To switch to the \b advanced option, click <em>"More..."</em> (see 
\ref figure_3 "Figure 3" ).

In the advanced mode you have a possibility to select products to be
installed. Each product can have several options of installation: you
have a possibility to use the native product (provided with Linux
distribution and installed in the system folders), install already
precompiled binaries, build the product from sources or not install it
at all. Available options and default option are taken from the XML
configuration file. You can mark the products you want to install by
clicking the corresponding radio-buttons in the list view in the left
part of the page.
\n Note, that some products may require some other pre-requisite
products to be installed (or these prerequisite products should be
already available on your computer). The installation procedure has a
special feature to automatically mark these products in the list
view. For example, in order to install \b PyQt it is necessary to have
<b>gcc, Python, Qt</b> and \b Sip installed. Therefore all these
products will also be  turned on when you check on \b PyQt. This
feature can be switched off by clicking the <em>"Automatic
dependencies"</em> checkbox. Turn on this checkbox if you want all
prerequisite products to be automatically checked when you select some
product to be installed. Turn off this checkbox if you want to disable
this feature.

\anchor figure_3
\image html productpage.png
\n <center><b>Figure 3:</b> "Installation settings" page in the 'advanced' mode</center>

If you want to use native products (like \b gcc, \b tcl, etc.), select <em>"use
native"</em> option. 
\n Special button in the right part of the page - <em>"Unselect All"</em> -
allows to reset quickly all products to the <em>"not install"</em> state.
<br><br>
There are also two checkboxes on this page: <em>"SALOME sources"</em>
and <em>"SALOME binaries"</em>. These three-state checkboxes allow
quick selecting/unselecting sources/binaries packages of SALOME
modules for installation.
<br><br>
In addition, when some SALOME sources are selected, one more check box
becomes available: <em>"Build SALOME sources"</em>. If this option is
turned on, the selected SALOME modules will be built and installed
from sources.

\note <b>If this check box is turned on, the corresponding SALOME
module binaries package installation is disabled, because of  SALOME
module sources and binaries packages conflict</b> (see \ref figure_4 "Figure 4" below).

\anchor figure_4
\image html productpage2.png
\n <center><b>Figure 4:</b> "Build SALOME sources" check box
usage</center>

The box at the right side of the page displays the information about
currently highlighted product: name, version and short description,
required disk space, disk space required for temporary files, list of
prerequisites (this information is provided in the XML file) and
current user choice.
<br><br>
The <em>"Disk space required:"</em> field displays how much disk space
on the hard drive is required for installation of selected products.

\note <b>Please, take into account that the displayed amount of
required disk space is approximate and may differ when you install
products on your hard drive.</b>

The installation procedure uses a special directory to store temporary
files. The <em>"Space for temporary files:"</em> field shows the information
about required disk space on the hard drive for extracting and
compiling the selected products. You can change the temporary
directory - just type a path to the folder you want to use or click on 
the corresponding <em>"Browse..."</em> button.

\note Actually, temporary files are not stored directly in the
directory entered by the user. The Installation Wizard creates an
additional folder in this directory named something like
INSTALLWORK<b>XXXXX</b> where XXXXX is a unique number. This allows to launch
several Installation Wizards simultaneously. This temporary directory
is removed automatically when the installation finishes.

The installation procedure also checks the available disk space. If
there is not enough disk space on your hard drive you will see a
corresponding error message box.

\note <b>You are strongly recommended not to use directory names
containing spaces</b>. Otherwise you can experience 
some troubles with the installation.

To proceed further click <em>"Next"</em>. At this moment the program will make
some tests to check installation settings: if there is enough disk
space on the hard drive, check for native products installation,
dependencies (prerequisites) for each product you have selected to be
installed. If any test fails you will see the corresponding warning
message box. Otherwise the wizard will proceed to the next page:

\anchor figure_5
\image html choicepage.png
\n <center><b>Figure 5:</b> "Check your choice" page</center>

This page summarizes the installation options you've made on the
previous pages. You can check again your choice and change it if
necessary by getting back to the previous page.
\n When you are sure that everything is OK, click <em>"Next"</em> to
follow to the \ref figure_6 "next page".

\anchor figure_6
\image html progresspage1.png
\n <center><b>Figure 6:</b> "Installation progress" page</center>

To start installation of the selected products click "Start". It
launches the shell installation script and you will be able to see the
output of the script in the  dialog topmost frame. If any errors occur
during the installation progress the corresponding messages will be
printed to the log window in bold red font.

It is possible to break the installation at any time by clicking
"Stop". Then you can get back to the previous pages if you wish to
change installation settings or restart installation by pressing again
"Start" button.

\note <b>In the current implementation it is not possible to resume
the stopped installation process; it will be re-started from the very
beginning.</b>

\anchor figure_7
\image html progresspage.png
\n <center><b>Figure 7:</b> "Installation progress" page: installation in progress</center>

The <em>"Installation Status"</em> frame window shows you the progress of
installation. \c "Waiting" status means that installation of this product
has not been started yet. The product currently being installed is
marked as \c "Processing". All installed products have \c "Completed"
status.

You can abort installation and close the installation procedure using
\em "Cancel" button.

\note <b>This button sends the signal "SIGTERM" to the shell
script. The script tries to clear all temporary files. The process of
removing temporary files can take some time, so the installation
wizard will wait 3 seconds before closing.</b>

At the end of installation (all selected products have been installed
successfully) you can go back to the previous pages to start a new
installation or click \em "Next" to go the Readme page:

\anchor figure_8
\image html readmepage.png
\n <center><b>Figure 8:</b> "Finish installation" page</center>

In this page you can read important information about the Instalation
Wizard itself and some tips: how to run and test SALOME or how to
build SALOME from the sources. This is the contents of the README file
which you can find in the root directory of the Installation Wizard.

You can also launch SALOME Desktop from this page or read the Release
Notes file by clicking on the corresponding buttons in the lower part
of the page (see \ref modifying_xml "here" and \ref finish_buttons
"here" for more information about customizing these buttons).

<br>
\anchor batch_mode_install
<h2>Batch mode</h2>

To launch the Installation Wizard in the batch mode use -\b b (--\b batch)
parameter.
\n In this mode the GUI wizard is not shown but all the installation
status is displayed directly in the console. In the batch mode the
user does not have a possibility to change installation settings which
are given in the configuration file, except target and temporary
directories which can be overridden by the corresponding command line
options.
\n The only exception is --\b all-from-sources (-\b a) option which enables
special installation mode in which all the products (including SALOME
modules) are installed from sources, ignoring the default mode defined
in the XML configuration file (see \ref installing_products "here" for details).

\anchor figure_9
\image html batchmode.png
\n <center><b>Figure 9:</b> Batch mode</center>

<br>
\anchor environment_files
<h2>Environment files</h2>

During the process of installation the script creates some environment
files to simplify the procedure of launching SALOME. These shell
scripts set all necessary environment variables for all products you
have installed. To learn how installation scripts collects the
environment, see \ref pick_up_env "here". These files are: \b
salome.csh + \b salome.sh in the <b><em>KERNEL module sources</em></b>
and <b><em>KERNEL module binaries</em></b> root directories and
\b env_products.csh + \b env_products.sh and \b env_build.csh + 
\b env_build.sh in the target installation directory.

\note there is some difference between these files: \b env_build.*
files are optimized to be used for building SALOME modules from
sources (see \b README file provided with the installation procedure
on the CD). The \b env_products.* (and \b salome.*) files are
optimized for SALOME launching. The behavior is defined by the
environment variable \b ENV_FOR_LAUNCH which is set to \b 0 in
env_build.* files and to \b 1 in env_products.* (salome.*) files.

<br>
<hr>
\anchor notes_on_check
<h2>Notes on <em>check products version</em> procedure</h2>

Unfortunately there is no exact algorithm to identify the product
version under Linux platform. The information in this section gives an
idea how the version is checked for the native/preinstalled products
(this information refers to the base platform <em>Linux Mandrake
10.1</em>; and the same algorithms are used for other platforms).

The general rule for all products is that the path to the binaries
should be set via the \b PATH environment variable, path to the libraries
should be set via the \b LD_LIBRARY_PATH variable and the python modules
should be available via the \b PYTHONPATH variable.

\note the information given in this section refers to the prerequisite
products for SALOME version 3.2.4.

<ul>
<li>gcc 3.4.1
\n\n Version number is checked by <b>gcc -dumpversion</b> command. The \b gcc
executable should be in the \b PATH environment variable. Version should
be equal to "3.4.1". It is recommended to use native gcc on Mandrake
10.1.<br><br>
</li>
<li>tcl/tk 8.4.5
\n\n Version number for \b tcl/tk can be found in tclConfig.sh and
tkConfig.sh files (\b TCL_VERSION and \b TK_VERSION variables
correspondingly). Version number should be equal to "8.4" (release
number is not checked). Set the \b TCLHOME environment variable to the
root directory of tcl/tk installation. It is recommended to use native
tcl/tk on Mandrake 10.1.<br><br>
</li>
<li>boost 1.31.0
\n\n Version number is defined by \b version.hpp file which is part of
the boost distribution. This file defines the \b BOOST_VERSION macro
which should be equal to "103100". In addition the existence of boost
libraries is checked. Set the \b BOOSTDIR environment variable if you
have a preinstalled version of boost.<br><br>
</li>
<li>Python 2.3.4
\n\n Version number is checked by \b python -\b V command. The \b python
executable should be in the \b PATH environment variable. Version
number should be equal to "2.3.4". It is recommended to use native
Python on Mandrake 10.1. Set the \b PYTHONHOME environment variable if
you have a preinstalled version of Python.<br><br>
</li>
<li>Swig 1.3.24
\n\n Version number is checked by \b swig -\b version command. The \b swig
executable should be in the \b PATH environment variable. Version number
should be equal to "1.3.24".
<br><br>
</li>
<li>Qt 3.3.3
\n\n Version number is defined by \b qglobal.h file which is part of the
Qt distribution. This file defines \b QT_VERSION_STR macro which should be equal to "3.3.3". It is recommended to use native Qt on Mandrake 10.1.
\n Set the \b QTDIR environment variable if you have a preinstalled version of qt.<br><br>
</li>
<li>msg2qm
\n\n \b msg2qm is a Qt tool which is used to convert text *.po files
to *.qm resource files. Unfortunately this tool is not included to the
Linux distribution and provided only in Qt sources package. This is
the reason why this tool is supplied with the SALOME Installation
Wizard. There is no way to check the version number of msg2qm tool. Just set
\b MSG2QM_ROOT environment variable if you have a preinstalled version
of msg2qm tool.<br><br>
</li>
<li>Open CASCADE 6.1.2a2
\n\n Version number is defined by \b Standard_Version.hxx file which
is part of the Open CASCADE distribution. This file defines \b
OCC_VERSION_MAJOR, \b OCC_VERSION_MINOR and \b OCC_VERSION_MAINTENANCE
macros which should refer to version 6.1.2. \n Set the CASROOT
environment variable if you have a preinstalled version of Open
CASCADE.<br><br>
</li>
<li>qwt 4.2.0/0.4.2
\n\n Version number is defined by \b qwt_global.h file which is part of
the qwt distribution. This file defines \b QWT_VERSION_STR macro which should be equal to "4.2.0".
\n Set the \b QWTHOME environment variable if you have a preinstalled version of qwt.<br><br>
</li>
<li>hdf 5-1.6.4
\n\n Version number is defined by \b libhdf5.settings file which is
part of the \b hdf5 distribution. Version should be equal to 1.6.4.
\n Set the \b HDF5HOME environment variable if you have a preinstalled
version of hdf5.<br><br>
</li>
<li>med 2.2.3
\n\n Unfortunately there is no formal way to check med version
number. We check existence of libmed.so.1.0.2 library on the
computer. If you have any problem with a preinstalled version of med,
please, reinstall it.
\n Set the \b MED2HOME environment variable if you have a preinstalled
version of med.<br><br>
</li>
<li>Vtk 4.2.6
\n\n Unfortunately there is no formal way to check VTK version
number. We just check the existence of \b libvtkCommon.so library on
the computer and hope that it is of version we need. If you have any
problem with a preinstalled version of Vtk, please, reinstall it.
\n Set the \b VTKHOME environment variable if you have a preinstalled
version of Vtk.<br><br>
</li>
<li>OmniORB 4.0.5, OmniORBpy 2.5, OmniNotify 2.1
\n\n We just check existence of some omniORB libraries and executable
on the computer, like \b libomniORB4.so.0.5, \b _omnipymodule.so.2.4,
\b libCOSNotify4.so.0.1 and \b notifd. \n Set the \b OMNIORBDIR
environment variable if you have a preinstalled version of omniORB
products.<br><br>
</li>
<li>sip 4.1
\n\n Version number is checked by \b sip -\b V command. The \b sip
executable should be in the \b PATH environment variable. Version number should be equal to "4.1".
\n Set the \b SIPDIR environment variable to the directory where you
have sip executable preinstalled.<br><br>
</li>
<li>PyQt 3.13
\n\n Version number is defined by \b pyqtconfig.py Python module file
which is part of the \b PyQt distribution. Version should be equal to "3.13".
\n Set the \b PYQTDIR environment variable if you have a preinstalled
version of PyQt.<br><br>
</li>
<li>netgen 4.5
\n\n Unfortunarely we can't find anything about netgen version. We
just check if \b NETGENROOT environment variable is set. \n Set the\b
NETGENROOT environment variable if you have a preinstalled version of
netgen mesher.<br>
\note netgen 4.5 provided with the SALOME installation Wizard has been patched to improve its performance.
</li>
<li>Numeric 23.7
\n\n Version number is checked by <b>python -c 'import Numeric; print
Numeric.__version__'</b> command. The \b python executable should be
in the \b PATH environment variable and \b Numeric module should be
available for the Python (for example it should be in the \b PYTHONPATH environment variable). Version number should be equal to "23.7". If you have any problem with a preinstalled version of Numeric 23.7, please, reinstall it.
\n Add the directory where you have a preinstalled version of Numeric
package to the the \b PYTHONHOME environment variable.<br><br>
</li>
<li>graphviz 2.2.1
\n\n Version number is checked by \b dot -\b V command. The dot
executable should be in the \b PATH environment variable. Version
number should be equal to "2.2.1". \n Add \b graphviz bin directory to
the the \b PATH environment variable.<br><br>
</li>
<li>doxygen 1.4.6
\n\n Version number is checked by \b doxygen --\b version command. The
\b doxygen executable should be in the \b PATH environment
variable. Version number should be equal to "1.4.6".<br><br>
</li>
<li>\b SALOME module \b sources (3.2.4).
\n\n For each SALOME module sources package (KERNEL, GUI, GEOM,
etc...) the root directory contains file configure.in (configure.ac)
which defines version information.\n Set the \b \<MODULE\>_SRC_DIR environment variable for each SALOME \b
MODULE sources package installed (where \b MODULE is KERNEL, GUI,
GEOM, ...).<br><br>
</li>
<li>\b SALOME module \b binaries (3.2.4)
\n\n For each SALOME module binaries package (KERNEL, GUI, GEOM,
etc...) the \b bin/salome directory contains file \b VERSION which
defines version information.\n Set \<MODULE\>_ROOT_DIR environment
variable for each SALOME \b MODULE binaries package installed (where
\b MODULE is KERNEL, GUI, GEOM, ...).<br><br>
</li>
</ul>

If you have native products installed to directories different from
default ones (not \b /usr/bin, \b /usr/lib...), it is recommended to follow
the above mentioned instructions. Or you should properly set \b PATH and
\b LD_LIBRARY_PATH variables \em before starting the Installation
Wizard. Otherwise the installation script will fail to find
preinstalled/native products.

\note for some native products (e.g. gcc, Python) the rules of version
checking are not so strict as described above. Only major and minor
version numbers should coincide with the prerequisite. Newer version
of the product can also be used. If some native product has version
number larger than that required by the installation procedure, the
user will be prompted by the warning message like this: "<em>You have
newer version of gcc installed on your computer than that is required
(3.4.1). Continue?</em>". You can click "\em Yes" to proceed with the
installation but in this case you should be aware of what you are
doing. SALOME binaries (including other products) are compiled with
the predefined prerequisites and most likely can not be run
successfully if these products are not found. This can be helpful only
if you plan to build all products from sources.

<br>
<hr>
\anchor pick_up_env
<h2>Pick up the <em>environment</em></h2>

Please, read the following information carefully . This section
describes how the installation procedure generates the environment
scripts for the SALOME platform being installed.
<br><br>
After installing each product shell the script creates a special
environment file for the product in its installation folder. The name
of the file is generated from the name of product by the following
scheme: \b env_<product_name>.sh (for example \b env_Vtk.sh for the
Vtk). This file includes all necessary environment settings. At the
final step of the installation the script picks up all the settings
files and generates two common environment files from them: \b salome.sh
and \b salome.csh for \b bash and \b csh shells correspondingly. Such approach
helps to save time when reinstalling products and you may not bother
about setting all environment variables manually to build/launch
SALOME. What you simply need is to source one of these environment
files.
<br><br>
This also concerns those products which are not being installed. For
example, you install some SALOME binaries to the directory where you
have previously installed other products.  The Installation procedure
tries to collect environment files from the target directory if it
finds necessary products installed there. If some product is not found
in the target directory the corresponding section of
\b salome.sh/salome.csh files will be skipped.
\n For native products (like \b gcc, \b tcl, etc...) the installation
procedure tries to find them first using \b PATH / \b LD_LIBRARY_PATH
variables and then in the system default directories (\b /usr/bin,
\b /usr/lib etc., depending on the product).
<br><br>
In any case you may edit \b salome.* files after the installation
procedure finishes, if you want.

\note As it was mentioned \ref environment_files "above" there are
other environment files which are generated by the installation
procedure: \b env_products.csh + \b env_products.sh and \b env_build.csh +
\b env_build.sh. These files can be found in the target installation root
directory.

<br>
<hr>
\anchor modifying_xml
<h2>Modifying <em>XML</em> configuration <em>file</em></h2>

You can create your own XML configuration file. The Installation
Wizard can then take it as a command line argument to provide a list
of products you want to install with it. The list of products and some
other settings for the Installation Wizard are provided in the XML
file. The default file which Installation Wizard looks for if no
command line arguments are given, is \b config.xml.
\n This section describes the structure of the configuration file. 
\n Optional sections/tags are in brackets.

\code
<document> 
    [ <config [ version=<install_wizard_version> ] 
              [ caption=<install_wizard_caption> ] 
              [ copyright=<install_wizard_copyright>  ] 
              [ license=<install_wizard_license_info> ] 
              [ os=<target_platform> ]
      /> 
    ] 
    [ <path   [ targetdir=<target_directory> ] 
              [ tempdir=<temp_directory>     ]
      /> 
    ] 
    [ <button   label=<button_label>      
              [ tooltip=<button_tooltip> ] 
                script=<button_script>    
              [ disable=<disable_flag>   ]
      /> 
    ] 
    [ <button ... 
      />
    ] 
    [ <product  name=<product_name> 
                version=<product_version> 
              [ context=<product_context>         ]
              [ description=<product_description> ]
                install=<installation_mode> 
                supported=<supported_installation_modes> 
              [ disable=<disable_flag>            ]
              [ pickupenv=<pickup_env_flag>       ]
                dependancies=<list_of_prerequisites> 
                installdiskspace=<install_disk_space> 
                temporarydiskspace=<tmp_disk_space> 
                script=<installation_script_name>
      /> 
    ] 
    [ <product ... 
      /> 
    ]
    ...
</document>
\endcode

<b>\<config\> section</b>
\n\n This is an optional section; it provides general information about
the Installation Wizard itself.
<br><br>
Attributes:
<ul>
<li><b>version</b>
\n\n The application version number to be shown in the caption.<br><br>
</li>
<li><b>caption</b>
\n\n The application main window caption - if this string contains
'\%1' text the title will contain the version number in this place (see
above).<br><br>
</li>
<li><b>copyright</b>
\n\n The application copyright information (shown in the first
page).<br><br>
</li>
<li><b>license</b>
\n\n The application license information (shown in the first
page).<br><br>
</li>
<li><b>os</b>
\n\n This parameter defines the directory (relative from
./Products/BINARIES) where the Installation Wizard will search
precompiled binaries packages. If this tag is not provided, binaries
packages are looked for in the ./Products/BINARIES directory.<br><br>
</li>
</ul>

<b>\<path\> section</b>
\n\n This is an optional section; it defines default installation
directories.
<br><br>
Attributes:
<ul>
<li><b>targetdir</b>
\n\n The target directory - the path to the directory where products
should be installed.<br><br>
</li>
<li><b>tempdir</b>
\n\n The temporary directory - the path to the directory for the
temporary files.<br><br>
</li>
</ul>

<b>\<product\> section</b>
\n\n This section describes product to be installed with the
Installation Wizard. The XML file should include a \<product\> section
for each product to be installed. The products appear in the tree view
and are installed in the order they are described in the configuration
file. It is recommended (but not obligatory) to define native products
at the top of the list before all other products.
<br><br>
Attributes:
<ul>
<li><b>name</b>
\n\n Product name.<br><br>
</li>
<li><b>version</b>
\n\n Product version.<br><br>
</li>
<li><b>description</b>
\n\n Product description (optional).<br><br>
</li>
<li><b>context</b>
\n\n Context (optional). The possible values are '<b>salome
sources</b>', '<b>salome binaries</b>' and '<b>prerequisite</b>'
(several contexts can be given separated by ":" symbol).<br><br>
</li>
<li><b>supported</b>
\n\n Supported modes of installation. Several modes can be separated
by comma. Possible value are: <em>install sources, install binaries, use
native</em>. The Installation script should contain the corresponding
functions for each of the supported installation modes (see
\ref installation_scripts "here").<br><br>
</li>
<li><b>install</b>
\n\n Default (starting) installation mode.<br><br>
</li>
<li><b>disable</b>
\n\n If this optional flag has 'true' value, the corresponding product
will not appear in the list of products and will not be
installed.<br><br>
</li>
<li><b>pickupenv</b>
\n\n This flag points that pickup environment procedure should be
performed for this product. If this flag equal to 'true',  salome.sh
and salome.csh files will  be created in the product installation
directory. Usually this option is set to true for SALOME KERNEL module
sources and binaries package. This is an optional key, default value
is 'false'.<br><br>
</li>
<li><b>dependancies</b>
\n\n List of prerequisite products, which are necessary to build this
product, separated by comma.<br><br>
</li>
<li><b>installdiskspace</b>
\n\n Total amount of space (integer, in Kbytes), which the product
occupies on the hard drive after the installation.<br><br>
</li>
<li><b>temporarydiskspace</b>
\n\n Disk space (integer, in Kbytes) for temporary files, which is
necessary to build the product from the sources.<br><br>
</li>
<li><b>script</b>
\n\n The installation script name. This script is in charge of the
installation of the product. It is called automatically by the
Installation Wizard when necessary from the main program. 
See the \ref installation_scripts "next section" for more information.<br><br>
</li>
</ul>

<b>\<button\> section</b>
\n\n This is an optional section. It allows customization of the last
"Finish installation" page of the Installation Wizard by adding one or
more buttons in the lower part of the wizard's window. The script
which is attached to each such button, can perform some specific
action, for example, launch the application or show the Release Notes
file by using an external program. See \ref finish_buttons "here" for
more details about writing scripts.<br><br>
Attributes:
<ul>
<li><b>label</b>
\n\n This is the button text.<br><br>
</li>
<li><b>tooltip</b>
\n\n The button tooltip (optional).<br><br>
</li>
<li><b>script</b>
\n\n The script attached to the button.<br><br>
</li>
<li><b>disable</b>
\n\n If this optional flag has 'true' value, the corresponding button
will not appear in the "<em>Finish installation</em>" page - the section of XML
file is silently ignored.<br><br>
</li>
</ul>

\note If you add new products to be installed with Installation
Wizard, you should also provide installation script for this
product. See the next section for more details.

<br>
<hr>
\anchor installation_scripts
<h2>Implementing <em>installation scripts</em> for the new products</h2>

When you want some product to be installed with the Installation
Wizard, you should add its description \ref modifying_xml "to the configuration file"
and create the installation script, following the rules described in this section.

There are some obligatory functions which should be implemented in
this installation script. These functions are automatically called by
the master installation script or/and its GUI shell when it is
necessary. \n File \b common.sh contains some service functions which can
be used in your installation script, like \b make_env(), \b make_dir(),
\b try_existing(), \b sort_path(), \b find_in_path(), etc.

<ul>
<li><b>check_version()</b>
\n\n This function allows to check the version of the product already
installed on the computer. It should try to find the product (native
or preinstalled in the target directory) and check its version. This
helps to avoid unnecessary reinstallation. This is an internal
function and is not called from the master installation
script.<br><br>
</li>
<li><b>try_native()</b>
\n\n This function is called when the 'use native' installation mode
is selected by the user. The function should try to find a native
version of the product and define possibility of its use. It should
create the environment file for the product in the temporary directory
(see also the description of \b print_env() function). It is not
necessary to implement this function if you do not provide native mode
installation.<br><br>
</li>
<li><b>install_source()</b>
\n\n This function is called when the 'install sources' installation
mode is selected by the user. The function is responsible for building
the product from the sources package. It should create the environment
file for the product in the temporary directory (see also description
of \b print_env() function). It is not necessary to implement this
function if you do not provide sources mode installation.<br><br>
</li>
<li><b>install_source_and_build()</b>
\n\n This function is called when SALOME module is installed and the
--\b all-from-sources (-\b a) option is used (<em>"Build SALOME sources"</em>
check box in GUI mode). This function should be used to unpack SALOME
sources package and then call the build/install procedure for it.
For more details please refer to the \ref installing_products "this"
and \ref gui_mode_install "this" sections for more details.<br><br>
</li>
<li><b>install_binary()</b>
\n\n This function is called when the <em>'install binaries'</em> installation
mode is selected by the user. The function is responsible for the
extracting of the product from the binaries package. It should create
environment for the product in the temporary directory (see also
description of \b print_env() function). It is not necessary to implement
this function if you do not provide binaries mode
installation.<br><br>
</li>
<li><b>try_preinstalled()</b>
\n\n This function is called when the 'not install' installation mode
is selected by the user. In this case the script should inspect the
target directory to try to find an already preinstalled product, pick
up and check the environment from there. See \ref pick_up_env "here" for more
details.<br><br>
</li>
<li><b>print_env()</b>
\n\n This function is in charge of creating the environment script. It
should create a file with name \b env_<product_name>.sh in the temporary
directory and then copy it into the product installation
directory. The file should contain all necessary environment variables
settings for the product. It will be collected during the
'pick-up-environment' procedure.<br><br>
</li>
<li><b>pickup_env()</b>
\n\n This procedure corresponds to the \b pickupenv tag of the
configuration xml file (see previous section). It should call the
\b make_env procedure to perform the pick-up environment procedure for
the product.<br><br>
</li>
</ul>

The calling signature of the product installation script is the following: 
<b>\<product_script_name\> \<function_name\> \<temp_folder\>
\<products_directory\> \<target_directory\> \<dependancies\>
\<product_name\></b>
\n\n where \n\n
<b>\<product_script_name\></b> - installation script name (described in the
configuration xml file);\n
<b>\<function_name\></b> - the name of function, corresponding to the selected
installation mode: \em try_native, \em install_source, \em install_binary or
\em try_preinstalled;\n
<b>\<temp_folder\></b> - temporary files directory;\n
<b>\<products_directory\></b> - directory where the sources/binaries package
can be found. You should provide the sources package in the
<em>\<Install_Wizard_root_directory\>/Products/SOURCES</em> directory and
binaries package in the
<em>\<InstallWizard_root_directory\>/Products/BINARIES/\<os_version\></em>, where
\<os_version\> is the target platform description, which appears in the
corresponding section of the \ref modifying_xml "configuration xml file";
<em>\<target_directory\></em> - root target directory where the product should be installed to; 
<em>\<dependancies\></em> - single-quoted list of prerequisite products, separated by space; 
<em>\<product_name\></em> - product name itself.

\b Example:
\n <em>med-2.2.3.sh install_binary /tmp/work
./Products/BINARIES/Mandrake10.1 /usr/salome 'gcc Hdf' med</em>

Copy the created script into the
<em>\<Install_Wizard_root_directory\>/config_files</em> sub-directory where all
installation scripts are stored. Installation Wizard will
automatically search and call your script during the installation
procedure.

<br>
<hr>
\anchor finish_buttons
<h2>Customizing <em>Readme page</em> buttons</h2>

The Installation Wizard allows customizing the look-n-feel of the last
<em>"Finish installation"</em> page. If you want to add one or more buttons to
this page in order to perform some specific actions at the end of the
installation (for example, to show the Release Notes file by using
Open Office) you can put an additional section to the XML
configuration file. This is the \b \<button\> section (see 
\ref modifying_xml "here" for more details).

To implement the action which will be performed when the user clicks
the button, you need to create a script and put it to the
<em>\<Install_Wizard_root_directory\>/config_files</em> directory.
\n There are some obligatory functions which should be implemented in
this script. These functions are automatically called by the
Installation Wizard GUI.

<ul>
<li><b>check_enabled()</b>
\n\n This procedure is called by the Installation Wizard when the
<em>"Finish installation"</em> page is displayed and the status of the buttons
should be modified according to the installation options. This
procedure should return \b 0 if the corresponding action can be performed
and, thus, the button should become enabled. Otherwise, it should
return \b 1 - in this case the corresponding button will be
disabled.<br><br>
</li>
<li><b>execute()</b>
\n\n This procedure is invoked when the user clicks the button. This
procedure should return \b 0 if the corresponding action is done
successfully and \b 1 if any error occurs.<br><br>
</li>
</ul>

The calling signature of the script is the following:
\n <b>\<product_script_name\> \<function_name\> \<target_directory\>
\<temp_folder\></b>
\n\n where \n\n
\b \<product_script_name\> - the script name itself (retrieved from the XML configuration xml file); 
\n \b \<function_name\> - the name of function; 
\n \b \<target_directory\> - root target directory where the product is installed to; 
\n \b \<temp_folder\> - temporary files directory;

\note The standard Installation Wizard buttons "Launch SALOME" and
"Release Notes" are implemented with this feature. Refer to scripts
\b start_salome.sh and \b release_notes.sh for sample implementation.

\note Any button (even standard) can be ignored by the Installation
Wizard if the attribute \b \<disable\> in the XML configuration file is set
to the "true" value.

*/