Copyright (C) 2007-2010  CEA/DEN, EDF R&D, OPEN CASCADE

Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com

=======================================
Set of scripts for a SALOME application
=======================================
*html version of this document is produced with docutils*::

  rest2html < doc.txt > doc.html

This document corresponds to SALOME2 3.1. (alpha version)

+-------------------------------------------+
| **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
+-------------------------------------------+

SALOME Application concept
--------------------------

See SALOME_Application_ to define your own configuration of SALOME and run it
on one or several computers. This is the recommended way of configuration.

.. _SALOME_Application: ../../doc/SALOME_Application.html


User run scripts
----------------

The SALOME user can use the following scripts:

runAppli
   Launches a SALOME Session
   (similar to ${KERNEL_ROOT_DIR}/bin/salome/runSalome but with a different
   name to avoid confusions).

runSession
   Launches a shell script in the SALOME application environment, with access
   to the current SALOME session (naming service), if any.
   Without arguments, the script is interactive. With arguments, the script
   executes the command in the SALOME application environment.

runConsole
   Gives a python console connected to the current SALOME Session.
   It is also possible to use runSession, then python.

runTests
   Similar to runSession, used for unit testing. runTests defines a new 
   configuration for naming service (new port number) to avoid interferences
   with a running SALOME session. runSession tries to use an already existing
   naming service definition from a running session (hostname & port number).

killCurrentPort
   Kills the last SALOME session corresponding to this application, and 
   intially launched from this computer.
   Cleans associated config files.

SALOME internal run scripts
---------------------------

envd
   Sets SALOME application environment, envd is sourced by other scripts.

getAppliPath.py
   Used by other scripts to define the Application Path.

searchFreePort.sh
   Used by other scripts to find a free port for naming service.

For remote calls, SALOME uses one script.

runRemote.sh
   This script is mainly used to launch containers. The first 2 arguments
   define the hostname and port userd for naming service, the remaining
   arguments define the command to execute.


The following files must be adapted to your environment and SALOME Application
------------------------------------------------------------------------------

- CatalogResources.xml
- SalomeApp.xml
- env.d/atFirst.sh
- env.d/envProducts.sh
- env.d/envSalome.sh

CatalogRessources.xml
   This files describes all the computer the application can use. The given
   example is minimal and suppose ${APPLI} is the same relative path
   to ${HOME}, on all the computers. A different directory can be set on a
   particular computer with a line::

       appliPath="my/specific/path/on/this/computer"

SalomeApp.xml
   This file is similar to the default given
   in ${GUI_ROOT_DIR}/share/salome/resources/gui


Proposal for env.d scripts
~~~~~~~~~~~~~~~~~~~~~~~~~~
Each user **must define** his own configuration for these scripts, following
the above rules. **The following is only an example not working as it is**.

atFirst.sh
    Sets the computer configuration not directly related to SALOME,
    like useful tools, default PATH.

envProducts.sh
    Sets the SALOME prerequisites.

envSALOME.sh
    Sets all the MODULE_ROOT_DIR that can be used in the SALOME application.

    SalomeAppConfig is also defined by::

      export SalomeAppConfig=${HOME}/${APPLI}

    where SalomeAppConfig designates the directory containing SalomeApp.xml. 
    Note that ${APPLI} is already defined by the calling scripts when 
    env.d/envSalome.sh is sourced.