================================================================================
                                     README
                           SALOME Installation Wizard
================================================================================

  Contents of this file:

  1. Running of the Installation Wizard

  2. Running of SALOME
     2.1. Setting of the environment for SALOME
     2.2. Launching of SALOME

  3. Installation notes
     3.1. Time required for the installation
     3.2. Log files
     3.3. Testing of the installed SALOME platform

  4. How to build SALOME modules from sources
     4.1. General procedure
     4.2. Automatic build procedure: build.sh script
     4.3. Build SALOME using cmake

================================================================================

  1. Running of the Installation Wizard

     The Installation Wizard can be launched in two modes: GUI and batch.
     The root directory of the Installation Wizard contains Python
     script runInstall. To run the Installation Wizard just type
     ./runInstall in the terminal window: 

     [ python ] ./runInstall [<options>]

     Without any option this script will launch the SALOME Installation
     Wizard in the default mode (GUI) with the default installation 
     parameters. The default mode can be overridden by using command 
     line options. Each option has short and long notations: 

     -g / --gui

     Runs the Installation Wizard in the GUI mode (this is the default
     mode).

     -b / --batch

     Runs the Installation Wizard in command-line mode.

     -f FILE / --file=FILE
    
     Defines the XML configuration file to be used by the Installation Wizard.
     If the appropriate file is not found, the warning message is shown. 
     If this option is not used then the installation script tries to
     define the Linux version and use the corresponding XML file. 
     For example, for the Linux Mandriva 2010.0 the config_Mandriva_2010.0.xml 
     file will be used by default.

     -d DIR / --target=DIR

     Defines the target directory for SALOME platform installation. 
     If used, this option overrides the default target directory, 
     indicated in the configuration XML file (usually 
     ${HOME}/salome_<version>). 

     -t DIR / --tmp=DIR

     Defines the directory for temporary files. If used, this
     option overrides the default temporary directory, indicated in 
     the configuration xml file (usually /tmp). 

     -a / --all-from-sources

     Forces all products to be installed from sources including SALOME
     modules. If this option is used all the default installation modes
     are ignored.

     -s / --single-directory
    
     Install all SALOME binaries packages to one directory (SALOME_<version>,
     where <version> is SALOME version).
     Note: this option is ignored when --all-from-sources (-a) option is used.
	     
     -h / --help

     Prints help information about available options.

     -v / --version

     Prints version information (Note: this is the version number of 
     the Installation Wizard, not of the SALOME platform). 

     For more detailed information about the Installation Wizard refer to the 
     readme.html file in the doc directory.

================================================================================

  2. Running of SALOME

     This section describes how to run SALOME platform after its installation 
     with the Installation Wizard.

     2.1. Setting of the environment for SALOME

          Installation Wizard 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. 
          These files are: 
               * env_products.csh + env_products.sh in the target directory;
                 these files can be used for the launching of SALOME.
               * salome.csh + salome.sh in the KERNEL module's sources/binaries
                 root directories; these files are the copies of the
                 corresponding env_products.* files.
               * env_build.csh + env_build.sh in the target directory;
                 these files contain minimal environment settings necessary
                 to build SALOME packages from sources (see paragraph 4).

          To set SALOME environment just type in the terminal window:

               cd <KERNEL_ROOT_DIR>
               source salome.sh
          or
               cd <KERNEL_ROOT_DIR>
               source salome.csh

          where <KERNEL_ROOT_DIR> is KERNEL binaries directory, e.g. 
          KERNEL_7.5.1 for the 7.5.1 version.

     2.2. Launching of SALOME
	
          After you set environment you can start SALOME. Go to the KERNEL 
          module's binaries directory (KERNEL_7.5.1/bin/salome for the version 
          7.5.1) by using of 'cd' command and then type:

               runSalome [<parameters>]

          This will start SALOME according to the launching parameters which
          are described in the configuration files: SalomeApp.xml in the 
          <GUI_ROOT_DIR>/share/salome/resources/gui folder and 
          .SalomeApprc.<version_number> file, located in your home
          directory (where <version_number> is SALOME version number).
          If the user configuration file does not exist, it is automatically
          created when exiting SALOME GUI.

          You can modify SALOME launching options by editing your 
          ~/.SalomeApprc.<version_number> file (not all the options are
          listed below):

          <section name="launch">
	    <parameter name="gui"        value="yes"/>
	    <parameter name="splash"     value="yes"/>
	    <parameter name="file"       value="no"/>
	    <parameter name="key"        value="no"/>
	    <parameter name="interp"     value="no"/>
	    <parameter name="logger"     value="no"/>
	    <parameter name="xterm"      value="no"/>
	    <parameter name="portkill"   value="no"/>
	    <parameter name="killall"    value="no"/>
	    <parameter name="modules"    value="GEOM,SMESH,MED,YACS,PARAVIS"/>
	    <parameter name="embedded"   value="SalomeAppEngine"/>
	    <parameter name="standalone" value="study,pyContainer,cppContainer,registry,moduleCatalog"/>
	  </section>

          Some parameters described in configuration file can be overridden by 
          using of corresponding command-line options for runSalome script:

	  -t, --terminal
	        Launch without GUI (in the terminal mode).
	  -g, --gui             
		Launch in GUI mode [default].
	  -d <1/0>, --show-desktop=<1/0>
                1 to activate GUI desktop [default], 0 to not activate
                GUI desktop (Session_Server starts, but GUI is not
                shown). Ignored in the terminal mode.
	  -o, --hide-desktop    
		Do not activate GUI desktop (Session_Server starts,
                but GUI is not shown). The same as --show-desktop=0.
	  -b, --batch           
		Launch in Batch Mode. (Without GUI on batch machine)
	  -l, --logger          
		Redirect messages to the CORBA collector.
	  -f <log-file>, --log-file=<log-file>
                Redirect messages to the <log-file>
	  -u <script1,script2,...>, --execute=<script1,script2,...>
                Python script(s) to be imported. Python scripts are
                imported in the order of their appearance. In GUI mode
                python scripts are imported in the embedded python
                interpreter of current study, otherwise in an external
                python interpreter
	  -r <file>, --resources=<file>
                Parse application settings from the <file> instead of
                default $(HOME)/.SalomeApprc.$(version)
	  -x, --xterm           
		Launch each SALOME server in own xterm console
	  -m <module1,module2,...>, --modules=<module1,module2,...>
		SALOME modules list (where <module1>, <module2> are
		the names of SALOME modules which should be available
		in the SALOME session)
	  -e <server1,server2,...>, --embedded=<server1,server2,...>
		CORBA servers to be launched in the Session embedded
		mode. Valid values for <serverN>: registry, study,
		moduleCatalog, cppContainer, SalomeAppEngine [by
		default the value from the configuration files is
		used]
	  -s <server1,server2,...>, --standalone=<server1,server2,...>
                CORBA servers to be launched in the standalone mode
                (as separate processes). Valid values for <serverN>:
                registry, study, moduleCatalog, cppContainer,
                pyContainer, supervContainer [by default the value
                from the configuration files is used]
	  -p, --portkill        
		Kill SALOME with the current port
	  -k, --killall         
		Kill all running SALOME sessions
	  -i <N>, --interp=<N>  
		The number of additional external python interpreters
                to run. Each additional python interpreter is run in
                separate xterm session with properly set SALOME 
		environment
	  -z <1/0>, --splash=<1/0>
                1 to display splash screen [default], 0 to disable
                splash screen. This option is ignored in the terminal
                mode. It is also ignored if --show-desktop=0 option is
                used.
	  -c <1/0>, --catch-exceptions=<1/0>
                1 (yes,true,on,ok) to enable centralized exception
                handling [default], 0 (no,false,off,cancel) to disable
                centralized exception handling.
	  --print-port          
		Print free port and exit
	  --nosave-config       
		Do not save current configuration
                        ${HOME}/.omniORB_last.cfg
	  --pinter              
		Launch with interactive python console.
	  --ns-port-log=<ns_port_log_file>
                Print Naming Service Port into a user file.
	  --gdb-session         
		Launch session with gdb
	  --version            
		Show program's version number and exit

          Additional launch settings are given in other sections, which refer to certain
          modules. For example, SMESH plugins which should be used in the SALOME launch 
          session can be mentioned in the <SMESH> section, e.g.:

	  <section name="SMESH">
	    <parameter name="name"       value="Mesh"/>
	    <parameter name="icon"       value="ModuleMesh.png"/>
	    <parameter name="plugins"    value="StdMeshers,NETGENPlugin"/>
	  </section>

================================================================================

  3. Installation notes

     3.1. Time required for the installation

          Installation of all products which are necessary to build and 
          start SALOME is a time-consuming process and needs from the user to be
          patient. 
          The quickest way to install SALOME is installation from the binaries. 
          In this mode the Installation Wizard just extracts all precompiled 
          products from the corresponding archives (except for the products
          which can be installed only by compiling from sources). 
          The installation from sources requires much more time than from 
          binaries because in this case the Installation Wizard extracts and 
          then builds each product using the product's own compilation 
          procedure.
          The installation time also depends on the computer and platform used.
          For example, to install SALOME on Pentium IV-3GHz, Linux Mandriva 2010.0,
          time of the installation is:

               - from binaries: ~15 minutes;
               - from sources: more than 20 hours.

     3.2. Log files

          The Installation Wizard displays the installation progress in the 
          corresponding windows (see readme.html). The Wizard uses a temporary 
          directory to store and build the products. During the installation 
          it produces some log files in this directory. If you suspect that
          the program hangs you can check the log files. These files have names
          in capital letters like CONFIGURE.LOG, MAKE.LOG, MAKEINSTALL.LOG, etc.

     3.3. Testing of installed SALOME platform

          There is a python script which allows quickly testing all SALOME
          modules. This script can help to check if SALOME has been installed
          successfully.
          To test SALOME platform, run SALOME desktop (see section 2), then 
          create a new study window (menu command 'File/New') and then type 
          in the study's embedded python console window:
 
               import salome_test

          When running, the script loads different modules (Geometry, Mesh, Med, 
          Post-Pro) and tests various functionalities of these 
          modules. You can watch the script execution progress in the embedded 
          python console window.

          Note: salome_test.py scripts require SALOME samples module 
          (SAMPLES_SRC) to be installed (this module includes a set of sample
          MED, Python, Supervisor graph, etc files).
          Environment variable DATA_DIR should point at the SALOME
          samples module directory.

================================================================================

  4. How to build SALOME modules from sources

     This section describes how to build SALOME modules manually 
     from the sources distribution provided with the Installation Wizard.

     4.1. General procedure

          SALOME build procedure is based on the GNU auto-tools:
          automake, autoconf, libtool, etc. This chapter describes the
          steps that should be done in order to compile and install
          SALOME modules using GNU aotu-tools. Note, that some modules support also
          cmake-based build procedure as alternative, moreover, for
          PARAVIS module only cmake-based procedure is
          available. Please refer to the paragraph 4.3 for more
          details about cmake-based build procedure.

          If you want to build SALOME modules from sources, install all prerequisite
          products, required for the platform and SALOME modules sources.
          Then follow the scenario described below.
          In this scenario it is supposed that you have installed SALOME
          modules sources in the /home/user/salome directory. The name of each module
          sources directory depends on the version of the platform, for example,
          KERNEL_SRC_7.5.1 for KERNEL module of SALOME version 7.5.1.

          Compilation and installation should be performed according to 
          the dependencies between modules:

          Main SALOME modules:

          * KERNEL -> no dependencies
          * GUI -> KERNEL
          * GEOM -> KERNEL, GUI
          * MED -> KERNEL, GUI
          * SMESH -> KERNEL, GUI, GEOM
          * YACS -> KERNEL, GUI
	  * PARAVIS -> KERNEL, GUI, MED
	  * HEXABLOCK -> KERNEL, GUI, GEOM
	  * HOMARD -> KERNEL, GUI, GEOM, SMESH
	  * JOBMANAGER -> KERNEL, GUI

          SMESH plugins:

          * NETGENPLUGIN -> KERNEL, GUI, GEOM, SMESH
          * GHS3DPLUGIN -> KERNEL, GUI, GEOM, SMESH
          * GHS3DPRLPLUGIN -> KERNEL, GUI, GEOM, SMESH
          * BLSURFPLUGIN -> KERNEL, GUI, GEOM, SMESH
	  * HexoticPLUGIN -> KERNEL, GUI, GEOM, SMESH, BLSURFPLUGIN 
          * HYBRIDPLUGIN -> KERNEL, GUI, GEOM, SMESH
	  * HEXABLOCKPLUGIN -> KERNEL, GUI, GEOM, SMESH, HEXABLOCK

          Sample modules:

          * COMPONENT -> KERNEL, MED
          * CALCULATOR -> KERNEL, MED
          * PYCALCULATOR -> KERNEL, MED
          * HELLO -> KERNEL, GUI
          * PYHELLO -> KERNEL, GUI
	  * LIGHT -> KERNEL, GUI
	  * PYLIGHT -> KERNEL, GUI
	  * ATOMIC -> KERNEL, GUI
	  * ATOMGEN -> KERNEL, GUI
	  * ATOMSOLV -> KERNEL, GUI, ATOMGEN
	  * RANDOMIZER -> KERNEL
	  * SIERPINSKY -> KERNEL, GUI, RANDOMIZER, SMESH

	  Other:
	  
	  * DOCUMENTATION -> no dependencies

          Note: SMESH plugins and sample modules are optional. You may skip 
          compiling them if you do not plan to use NETGEN and/or GHS3D meshing
          algorithms and do not want to build samples.

          Note: Meshing plug-ins BLSURFPLUGIN, HexoticPLUGIN, GHS3DPLUGIN,
          GHS3DPRLPLUGIN and HYBRIDPLUGIN require commercial license for the Distene
          meshers in runtime mode. Moreover, BLSURFPLUGIN requires
          blsurf product at the compilation time. Without it, the
          BLSURFPLUGIN meshing plugin compilation will fail. Refer
	  to http://www.distene.com/ for more details.

          In general, each module (except for KERNEL and GUI) is 
          optional for SALOME. If you do not need a certain module, just do not 
          compile or install it. But remember that some modules require others 
          to be built first (see dependencies table above).

          To build KERNEL module:

          - go to installation root directory (/home/user/salome in this example):

               cd /home/user/salome

          - to set environment variables use bash or csh script, depending on 
            your shell:

               source ./env_products.csh
            or
               source ./env_products.sh

          - create build directory for the KERNEL module:

               mkdir KERNEL_build
               cd KERNEL_build

          - create a configuration script by typing

               ../KERNEL_SRC_7.5.1/build_configure

          - run configure script which will check the environment and create 
	    Makefile files:

               ../KERNEL_SRC_7.5.1/configure --prefix=/home/user/salome/KERNEL-7.5.1

          Note, that --prefix option defines the directory where you want to 
          install KERNEL module after 'make install' procedure. configure script
          also accepts a lot of other parameters (for example, to build the module
          in the Release mode use --disable-debug --enable-production keys).
          You can learn more about the configure of any modules by using --help (-h) 
          parameter.

          - build and install KERNEL module:

               make
               make install

          After you have completed this scenario, KERNEL module is built and 
          installed into /home/user/salome/KERNEL-7.5.1 directory.

          - modify your environment scripts:

          * for bash:

               export KERNEL_ROOT_DIR=/home/user/salome/KERNEL-7.5.1

          * for csh:

               setenv KERNEL_ROOT_DIR /home/user/salome/KERNEL-7.5.1

          - then repeat this scenario for other modules you want to build taking 
            into account the dependencies between modules (see dependencies table
            above).

          Note: if the compilation fails it may be caused by bad environment. 
          In this case you should check if the environment script that you use 
          (salome.csh or salome.sh) contains the following lines for each module MODULE:

          * for bash:

               export MODULE_ROOT_DIR=/home/user/salome/<MODULE_distribution>

          * for csh:

               setenv MODULE_ROOT_DIR /home/user/salome/<MODULE_distribution>

          where <MODULE_distribution> is a MODULE-7.5.1 (see above).

     4.2. Automatic build procedure: build.sh script

          SALOME Installation Wizard includes build.sh script which can be used
          for automatic building of SALOME modules from sources packages.
          This script is copied into the top-level installation directory
          (the same directory where env_products.[c]sh files are generated).

          To use the script just install SALOME sources packages with the
          Installation Wizard, then cd to the SALOME installation directory
          and type:

               ./build.sh

          By default, build.sh builds and installs all SALOME
          modules. All modules are installed to the INSTALL subfolder
          of the current directory. If you need to change the installation
          directory, you can use -p <prefix> option where <prefix> is the
          directory SALOME modules should be installed to.

          If you want to build only some subset of SALOME modules,
          just pass them as parameters, e.g.:

               ./build.sh -p /home/user/salome KERNEL MED GEOM

          The script also provides other options which specify compiling and 
          installation parameters. You can learn about these options by using
          -h key:

               ./build.sh -h

          Note: to avoid collisions it is recommended to avoid installation of
          SALOME binaries packages with Installation Wizard if you plan to build
          SALOME modules from sources packages; if you still install binary
	  packages of SALOME module, you can manually edit env_products.[c]sh
	  scripts by commenting all rows concerning environment of SALOME
	  binaries packages.

          Note: use -d option of the build.sh script carefully because
	  when this option is specified to the script, it can remove
          the existing (previously installed) SALOME modules.

          Note: build.sh script does not modify the environment files
          (env_products.[c]sh, env_build.[c]sh). You should do it by yourself.

     4.3. Build SALOME modules manually

          The build procedure of all SALOME modules is implemented with
	  CMake. This paragraph describes the steps that can be done in
          order to build SALOME modules manually.

          For example, to build KERNEL module:

          - go to installation root directory (/home/user/salome in this example):

               cd /home/user/salome

          - to set environment variables use bash or csh script, depending on 
            your shell:

               source ./env_products.csh
            or
               source ./env_products.sh

          - create build directory for the KERNEL module:

               mkdir KERNEL_build
               cd KERNEL_build

          - run cmake

               cmake -DCMAKE_INSTALL_PREFIX=/home/user/salome/KERNEL-7.5.1 ../KERNEL_SRC_7.5.1

          Note, that -DCMAKE_INSTALL_PREFIX option defines the directory where you want to 
          install KERNEL module after 'make install' procedure. You
          can supply additional options to the cmake (for example, to
          build the module in the Release mode use -DCMAKE_BUILD_TYPE=Release option).

          - build and install KERNEL module:

               make
               make install

          After you have completed this scenario, KERNEL module is built and 
          installed into /home/user/salome/KERNEL-7.5.1 directory.

          - modify your environment scripts:

          * for bash:

               export KERNEL_ROOT_DIR=/home/user/salome/KERNEL-7.5.1

          * for csh:

               setenv KERNEL_ROOT_DIR /home/user/salome/KERNEL-7.5.1

================================================================================