local cur prev command options
COMPREPLY=( )
_get_comp_words_by_ref -n = cur prev
- commands='start context shell connect kill killall test info help coffee car'
+ commands='start context shell connect kill killall test info doc help coffee car'
# Algorithm:
# If cursor is at index 1
context Initialize SALOME context. Current environment is extended.
shell Initialize SALOME context, attached to the last created SALOME
instance if any, and executes scripts passed as command arguments.
- User works in a Shell terminal; SALOME environment is set but
+ User works in a Shell terminal. SALOME environment is set but
application is not started.
connect Connect a Python console to the active SALOME instance.
kill <port(s)> Terminate SALOME instances running on given ports for current user.
Module names must be separated by blank characters.
help Show this message.
-If no command is given, default to start.
+If no command is given, default is start.
Command options:
================
- Use salome <command> --help to show help on command ; available for commands:
- start, shell, connect, test, info.
+ Use salome <command> --help to show help on command. Available for the
+ following commands: start, shell, connect, test, info.
--config=<file,folder,...>
==========================
application on several computers.
See \subpage SALOME_Application to define your own configuration of %SALOME and run it
on one or several computers. This is the recommended way of configuration.
--# <b>How to launch %SALOME</b>:
- - Using the python \subpage salome_command.
+-# <b>How to launch %SALOME</b>\n
+ Use the python \subpage salome_command.
-# <b>How to use KERNEL services in Python scripts</b>\n
The %SALOME KERNEL offers a list of services available in Python. See \subpage KERNEL_Services.
-# <b>How to use KERNEL services from a C++ context</b>\n
/*!
- \page SALOME_Application Salome Application Concept
+ \page SALOME_Application Salome Application Concept
The following explains how to configure your own application with your list of
modules, how to define and run this application on one or more computers.
+You can choose one of the following approaches:
+-# use an \ref sec_salome_profile
+-# use a \ref sec_virtual_appli
\section S1_sal_appl General principles
-%A %SALOME application is defined by :
+%A %SALOME application is defined by:
- a set of modules (GEOM, SMESH, ASTER...)
-- a profile: set of informatic resources (images, documentation, tests...) binding the modules together.
-- a launcher: python script that creates a context (set of environment variables usable by the SALOME modules) and runs an instance of SALOME.
-
+- a set of informatic resources (images, documentation, tests...) binding the modules together, also called profile.
+- a launcher: a python script that creates a context (set of environment variables usable by the %SALOME modules) and runs an instance of %SALOME.
-%A %SALOME User can define several %SALOME Applications. These applications are
-runnable from the same user account. These applications may share the same
+%A %SALOME user can define several %SALOME applications. These applications are
+runnable from the same user account. These applications may share the same
KERNEL and modules. Thus, the application configuration is independant of
KERNEL and must not be put in KERNEL_ROOT_DIR.
Furthermore, prerequisites may not be the same on all the applications.
-%A %SALOME Session can run on a several computers.
+%A %SALOME session can run on a several computers.
Binary modules and prerequisites are installed on the different computers.
There is no need to have all the modules on each computer (the minimum is
password (key exchange for ssh). Account may be different on each
computer.
-\section S2_sal_appl Generation of a profile
+
+\section sec_salome_profile Application profile
The user can generate a default profile for its application using the following command:
\code
context variable <b>SalomeAppConfig</b> to the path where the profile is installed.
-\section S3_sal_appl Deprecated Application Directory
+\section sec_virtual_appli Virtual application
First, the user must create a %SALOME application configuration file by modifying a
copy of ${KERNEL_ROOT_DIR}/bin/salome/config_appli.xml.
The file describes the list of %SALOME modules used in the application, with
their respective installation path. The configuration file also defines the
path of an existing script which sets the %SALOME prerequisites (tag "prerequisites"),
-and optionally, the path of samples directory (SAMPLES_SRC) (tag "samples")
+and optionally, the path of samples directory (SAMPLES_SRC) (tag "samples")
and the path of a catalog of resources (tag "resources").
The following command:
For a distributed application (several computers), one must copy and adapt
CatalogResources.xml from ${KERNEL_ROOT_DIR}/bin/salome/appliskel (see below).
-\section S4_sal_appl Deprecated general rules
-
-The application directory must be created on each computer of the application.
-The easiest way is to use the same relative path (to ${HOME}) on each computer.
-(Sometimes it is not possible to use the same path everywhere, for instance
-when ${HOME} is shared with NFS, so it is possible to define different path
-following the computers).
-
-The application directory contains scripts for environment and runs. Environment
-scripts must be configured (by the user) on each computer. All the environment
-scripts are in the env.d subdirectory.
-
-The script envd sources \b all the files (*.sh) in subdirectory env.d
-in alphanumeric order (after edition, think to remove backup files). The envd
-script is used by run scripts.
-
-<ol>
- <li>
-<b>env.d scripts</b>
-
-<b>env.d scripts are built automatically.</b>
-
-You can add your own environment scripts in env.d subdirectory, they will be sourced as
-the generated ones provided they have a .sh extension.
-
- </li>
- <li>
-<b>User run scripts</b>
-
-The %SALOME user can use 4 scripts:
-
-- runAppli\n
- Launches a %SALOME Session
- (similar to ${KERNEL_ROOT_DIR}/bin/salome/runSalome but with a different
- name to avoid confusions). See parameters below.
-
-- runSession\n
- Launches a shell script in the %SALOME application environment, with access
- to the current (last launched) %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\n
- Gives a python console connected to the current %SALOME Session.
- It is also possible to use runSession, then python.
-
-- runTests\n
- Similar to runSession, used for unit testing, but runSession tries to use an
- already existing naming service definition from a running session (hostname
- and port number), and runTests defines a new configuration for naming service
- (new port number).
- </li>
- <li>
-<b>%SALOME internal run scripts</b>
-
-- envd\n
- Sets %SALOME application environment, envd is sourced by other scripts.
-
-For remote calls, %SALOME uses one script.
-
-- runRemote.sh\n
- This script is mainly used to launch containers. The first 3 arguments
- define the hostname and port userd for naming service, plus a working directory, the remaining
- arguments define the command to execute.
- </li>
- <li>
-<b>Other configuration files</b>
-
-- SALOMEApp.xml\n
- This file is similar to the default given
- in ${GUI_ROOT_DIR}/share/SALOME/resources/gui
-
-
-- CatalogRessources.xml\n
- This file describes all the computers the application can use. The given
- example is minimal and suppose application directory is the same relative path
- to ${HOME}, on all the computers. %A different directory can be set on a
- particular computer with a line:
- \code
-appliPath="my/specific/path/on/this/computer"
- \endcode
-
- </li>
-</ol>
-
-\section S5_sal_appl Deprecated examples of use
-
-<ol>
- <li>
-<b>Launch a %SALOME session with a GUI interface</b>
-
-Launch is done with a command like:
-
-\code
-./runAppli --logger
-\endcode
-
-The --logger option means here : collect all the traces from the all the
-distributed process, via CORBA, in a single file : logger.log.
-
-There are a lot of options, a complete list is given by:
-
-\code
-./runAppli --help
-\endcode
-
-Note that, without argument, runAppli is a non interactive Python application,
-and, with arguments, runAppli is an interactive Python interpreter.
-
-Several options are already defined by default in SALOMEApp.xml files. Optional
-arguments given in the command override the SALOMEApp.xml configuration.
-
-Several sessions can run simultaneously, each session use a different port for
-CORBA naming service, so the sessions are totally separated from each other.
-
-When the GUI is closed, the different %SALOME servers are still running.
- </li>
- <li>
-<b>Close a %SALOME session, kill all the servers</b>
-
-Inside the interactive python interpreter you get when you use runAppli
-with arguments, you can kill all the servers of your session with:
-
-\code
->>> killLocalPort()
-\endcode
-
-or the servers of all the sessions with:
-
-\code
->>> killAllPorts()
-\endcode
-
-If you have no active Python interpreter connected to your session, you can
-kill all the %SALOME servers of <b>all the sessions</b> on a given computer:
-
-\code
-./runSession killSalome.py
-\endcode
-
-Remember! it's the same idea in <b>Windows (R) operating system</b> (Microsoft and Windows are either registered trademarks or trademarks of
- Microsoft Corporation in the United States and/or other countries) :
-use the start menu to stop...
-
-When you use only one session at a time, you don't need more.
-
-To kill a given session (when several session are running), one needs
-the naming service port number:
-
-\code
-./runSession killSalomeWithPort 2810
-\endcode
-
-Note that the port number of the last launched session can be found on Linux,
-in the prompt, within a runSession shell (see below).
-
-It is also possible to get the Naming Service host and port number of
-the last launched session with:
-
-\code
-./runSession NSparam.py
-\endcode
-
- </li>
- <li>
-<b>Launch a %SALOME session without GUI interface</b>
-
-This is used to launch a %SALOME Python script without GUI
-(no GUI %server = SALOME_session_server)
-
-Example of script (test_session_geom.py):
-
-\code
-import salome_session
-salome_session.startSession(modules=["GEOM"])
-import GEOM_usinggeom
-raw_input("Press a key and the servers will be killed ...")
-\endcode
-
-This script is run in a non interactive way with:
-
-\code
-./runSession python test_session_geom.py
-\endcode
-
-All the process are automatically killed when Python is closed
-(with SALOME_session delete).
- </li>
- <li>
-<b>Add an external Python interpretor to a running session</b>
-
-It's often easier to develop and try Python scripts outside the GUI embedded
-Python interpreter. Imagine, for instance, you are writing a script involving
-geometry and mesh modules.
-first, launch a %SALOME session with gui, then, on another terminal:
-
-\code
-./runSession
-python
-\endcode
-
-Import salome module. salome_init() without arguments creates a new study
-in the running session (note: salome_init(n) attachs to a running session whose
-studyId is n):
-
-\code
-import salome
-salome.salome_init()
-\endcode
-
-An example of script given with SMESH:
-
-\code
-import ex01_cube2build
-\endcode
-
-It is possible to connect the GUI interface to the study created in the above
-script with the file/connect menu, then browse study and display objects.
-Further modifications on study can be done either with GUI or external script
-(use refresh popup in GUI %object browser to see study modifications generated
-by the external script). <b>AVOID modifications with GUI when a Python script
-is running</b>. Not all the modules are protected against concurrent actions...
- </li>
- <li>
-<b>Different uses of the runSession shell interpreter</b>
-
-runSession invoked without arguments gives an interactive shell with the full
-environment of %SALOME (PATH, LD_LIBRARY_PATH, PYTHONPATH, other variables).
-If there are running sessions of the same %SALOME application, runSession
-connects to the last launched session (i.e. gets the naming service references
-of the session: hostname and port)
-
-On Linux, the shell prompt (bash) gives information on naming service
-references, hostname and port:
-
-\code
-[NS=cli76cc:2811]prascle@cli76cc:~/SALOME2/Run/Virtual$
-\endcode
-
-If there is no running session, prompt looks like:
-
-\code
-[NS=:]prascle@cli76cc:~/SALOME2/Run/Virtual$
-\endcode
-
-runSession is useful to launch any script or program which needs the complete
-%SALOME environment, with or without a session already running.
-For instance, to launch the ddd debugger interface on the gui %server, first
-launch a %SALOME session with gui, then, on another terminal:
-
-\code
-./runSession ddd
-\endcode
-
-Then attach to the running SALOME_Session_Server process.
- </li>
-</ol>
+The application directory contains the elements required to run %SALOME, for example the \ref salome_command, and some context files in env.d directory.
*/
/*!
\page salome_command salome command
-To start SALOME a new approach is proposed, based on \ref SALOME_Application. The underlying mechanism aims at:
+To start %SALOME a new approach has been introduced in versions 7.x, based on \ref SALOME_Application. The underlying mechanism aims at:
-# Unifying start commands\n
-Unix Shell scripts like runAppli, runSession and runConsole are replaced by a unique Python command named \b salome.
--# Handle execution context\n
-After SALOME exit, environment is restored to its initial state. No Shell file sourcing is required; context management is achieved using Python standard API for context files parsing.
--# Promote creation of custom start commands (launchers)\n
-A launcher is a Python script that creates an execution context then starts SALOME in this context. It uses methods provided by an Application Programming Interface (API). The \b salome command is a launcher. Several launchers may exist simultaneously; each uses the same API and focuses on execution context creation.
+Former unix Shell scripts like runAppli, runSession and runConsole have been replaced by a unique Python command named \b salome.
+-# Handling execution context\n
+After %SALOME exit, environment is restored to its initial state. No Shell file sourcing is required. Context management is achieved using Python standard API for context files parsing.
+-# Promoting creation of custom start commands (launchers)\n
+%A launcher is a Python script that creates an execution context then starts %SALOME in this context. It uses methods provided by an Application Programming Interface (API). The \b salome command is a launcher. Several launchers may exist simultaneously. Each one uses the same API and focuses on the execution context creation.
\section salome_launcher The salome command
Commands are:
- \c start \n
-Start a new SALOME instance.
+Start a new %SALOME instance.
- \c context \n
-Initialize SALOME context. Current environment is extended.
+Initialize %SALOME context. Current environment is extended.
- \c shell \n
-Initialize SALOME context, attached to the last created SALOME instance if any, and executes scripts passed as command arguments. User works in a Shell terminal; SALOME environment is set but application is not started.
+Initialize %SALOME context, attached to the last created %SALOME instance if any, and executes scripts passed as command arguments. User works in a Shell terminal. %SALOME environment is set but application is not started.
- \c connect \n
-Connect a Python console to the active SALOME instance.
+Connect a Python console to the active %SALOME instance.
- \c kill <port(s)> \n
-Terminate SALOME instances running on given ports for current user. Port numbers must be separated by blank characters.
+%Terminate %SALOME instances running on given ports for current user. Port numbers must be separated by blank characters.
- \c killall \n
-Terminate *all* SALOME running instances for current user ; do not start a new one.
+%Terminate *all* %SALOME running instances for current user. Do not start a new one.
- \c test \n
-Run SALOME tests.
+Run %SALOME tests.
- \c info \n
-Display some information about SALOME.
+Display some information about %SALOME.
+- \c doc <module(s)> \n
+Show online module documentation (if available). Module names must be separated by blank characters.
- \c help \n
Show this message.
+If no command is given, default is start.
+
+Use salome <command> --help to show help on command? Available for the following commands: start, shell, connect, test, info.
+
+\subsection Examples
To start an application, use \code salome start \endcode
-This command is equivalent to runAppli. It accepts the same options that can be listed using \code salome start --help \endcode
+To see available options for this command, use \code salome start --help \endcode
-To initialize an environment, use \code salome shell \endcode
-This command is equivalent to runSession. It accepts the same options that can be listed using \code salome shell --help \endcode
+To initialize %SALOME context, use \code salome shell \endcode
+To see available options for this command, use \code salome shell --help \endcode
To connect a Python console, use \code salome connect \endcode
-There is no options to this command. It asks user which SALOME instance to connect to.
+There is no options to this command. It asks user which %SALOME instance to connect to.
\section context_files Context files management
-The <tt>--config</tt> option is used to identify the list of configuration files or directories to be used for SALOME context creation. When this option is given, only files provided by user are considered. If user does not specify any context file SALOME will rely on context files detected in the env.d application folder. Two file formats can coexist, with a .cfg or .sh extension that are associated with the new and the former start mechanism, respectively.
-
-The \c salome command is based on the .cfg format; however, it is able to interpret (partially) the .sh format for software backward compatibility. The use of .cfg format is highly recommended with the new launcher.
+The <tt>--config</tt> option is used to identify the list of configuration files or directories to be used for %SALOME context creation. When this option is given, only files provided by user are considered. If user does not specify any context file %SALOME will rely on context files detected in the env.d application folder. Context files have the .cfg extension.
-It is possible to add context files in the env.d folder; the strategy followed by \c salome
-for these files is as follows. All files with .cfg extension are taken into account. Files with .sh extension are taken into account only if there is no file with the same name with
-a .cfg extension, for example:
--# Context1.cfg : taken into account because it has a .cfg extension.
--# Context2.cfg : taken into account because it has a .cfg extension.
--# Context2.sh : not taken into account because Context2.cfg exists.
--# Context3.sh : considered because Context3.cfg does not exist.
-
-Considered .sh files are automatically translated to .cfg format (the .cfg file is not written to disk). The translator is not as complete as Unix Shell interpreter; malfunctions may emerge in case of unrecognized syntax.
+To initialize application context, the \c salome command parses all context files in the env.d folder. User can add her own context files (see \ref context_file_syntax).
\section several_scripts_multiple_args Run several scripts with multiple arguments
On the one hand, runAppli options allow to give a list of Python scripts to be run after application startup; but it is not possible to specify parameters for these scripts. On the other hand runSession can run one script but it admits several parameters.
-The \c salome command combines the two solutions: you can specify multiple scripts, each can have several parameters. For this, the following syntax must be used; to provide parameters to a script from the command line, we write <tt>script.py args: arg1, arg2, ..., argn</tt>
+The \c salome command options allow to give a list of Python scripts to be run after application startup. It is possible to specify parameters for each of these scripts. To provide parameters to a script from the command line, write <tt>script.py args:arg1,arg2,...,argn</tt>
The script parameters must be separated by commas and no spaces are allowed (except
between the script name and the beginning of its parameters).
-For example, the following call will run sequentially three scripts, which will wait 5 seconds, say hello, and calculate 1 +2 +3:
+For example, the following call will run sequentially three scripts, which will wait 5 seconds, say hello, and calculate 1+2+3:
\code
salome shell –p 2811 wait.py args:5 hello.py add.py args:1,2,3
\endcode
salome shell -- python -tt hello.py
\endcode
+
\section handling_concurrency Handling concurrent starts
-A SALOME instance uses a dedicated TCP port number on which the CORBA name server of each SALOME application will connect. This refers to a technical solution that allows multiple software components belonging to the same application to communicate with each other. This approach is a standard used when multiple applications are running at the same time (components should not interfere with each other), and when application components can be distributed across multiple machines.
+%A %SALOME instance uses a dedicated TCP port number on which the CORBA name server of each %SALOME application will connect. This refers to a technical solution that allows multiple software components belonging to the same application to communicate with each other. This approach is a standard used when multiple applications are running at the same time (components should not interfere with each other), and when application components can be distributed across multiple machines.
-Each SALOME application owns a specific port number. This port is determined automatically when application starts. When multiple applications are started at the same time, assigning a number to each port could be conflicting, and the same port could be assigned to several applications. To prevent from such a situation, a Python object named \c Portmanager has been implemented. This object has been introduced in SALOME 7 as an optional tool, then evaluated on Linux and Windows. In SALOME 8, this object becomes the standard.
+Each %SALOME application owns a specific port number. This port is determined automatically when application starts. When multiple applications are started at the same time, assigning a number to each port could be conflicting, and the same port could be assigned to several applications. To prevent from such a situation, a Python object named \c Portmanager has been implemented. This object has been introduced in %SALOME 7 as an optional tool, then evaluated on Linux and Windows. In %SALOME 8, this object becomes the standard.
-Several instances can be safely started concurrently. For example in an automated process, calling several times the following commands (WORK_DIR variable changes at each call):
+Several instances can be safely started concurrently. For example in an automated process in shell script, calling several times the following commands (WORK_DIR variable changes at each call):
\code
salome start -t --ns-port-log=${WORK_DIR}/session.log
salome shell -p `cat ${WORK_DIR}/session.log` ${SALOME_APPLI_FOLDER}/bin/salome/waitContainers.py # may be optional
salome kill `cat ${WORK_DIR}/session.log`
\endcode
+From a Python script, use a SalomeInstance object:
+\code
+from salome_instance import SalomeInstance
+instance = SalomeInstance.start()
+print "Instance created and now running on port", instance.get_port()
+...
+instance.stop()
+\endcode
+
+
\section remote_calls Remote calls
-With \c salome \c shell user can connect to a SALOME instance running on a remote computer. In this case the options <tt>-p PORT</tt>, <tt>-m MACHINE</tt>, <tt>-d DIRECTORY</tt> and <tt>-u USER</tt> must be provided. Moreover syntax <tt>out:res1,res2,...</tt> can be used to get results back from remote machine.
+With \c salome \c shell user can connect to a %SALOME instance running on a remote computer. In this case the options <tt>-p PORT</tt>, <tt>-m MACHINE</tt>, <tt>-d DIRECTORY</tt> and <tt>-u USER</tt> must be provided. Moreover the syntax <tt>out:res1,res2,...</tt> can be used to get results back from remote machine.
For example:
\code
salome shell -m remotemachine -p 2810 -u myself -d /full/path/to/salome concatenate.py args:file1.txt,file2.txt out:result.txt
\endcode
-In this example user <tt>myself</tt> connects to <tt>remotemachine</tt> to run the script <tt>concatenate.py</tt> in a SALOME instance running on port <tt>2810</tt>; the script takes two input parameters and produces one result file.
-The script and the input files are on the local computer. They are copied to the remote machine using a secure connection ; results produced on remote computer are transferred on the local machine using the same protocol. Script, input files and results are removed from remote machine.
+In this example user <tt>myself</tt> connects to <tt>remotemachine</tt> to run the script <tt>concatenate.py</tt> in a %SALOME instance running on port <tt>2810</tt>. The script takes two input parameters and produces one result file.
+The script and the input files are on the local computer. They are copied to the remote machine using a secure connection. Results produced on remote computer are transferred on the local machine using the same protocol. Script, input files and results are finally removed from remote machine.
\section write_launcher How to write a launcher
-A launcher is a Python module that contains a single <tt>def main(args)</tt> function to sequentially execute the following operations:
+%A launcher is a Python module that contains a single <tt>main(args)</tt> function to sequentially execute the following operations:
- Detect application path
\code
-currentPath = os.path.dirname( os.path.abspath( __file__ ) )
+currentPath = os.path.realpath(os.path.dirname(os.path.abspath(__file__)))
launcherFile = os.path.basename(__file__)
from salome_starter import initialize
initialize(currentPath, launcherFile)
\endcode
-- Identify configuration (context) files
+- Identify context files
\code
from salomeContextUtils import getConfigFileNames
configFileNames, args, unexisting = getConfigFileNames(args, checkExistence=True)
# context.addToPythonPath('mypythonpath')
# context.setVariable('myvarname', 'value')
\endcode
-- Run SALOME
+- Run %SALOME
\code
-(out, err), returncode = context.runSalome(args)
+out, err, returncode = context.runSalome(args)
\endcode
This module is generally used as a script, run from a shell command line. It thus contains the directive:
\section salome_api The API
-An API named \c SalomeContext, written in Python, allows for the construction of SALOME execution context and for application start. Each launcher creates a \c SalomeContext object, and optionally gives it a list of configuration files to describe the context:
+An API named \c SalomeContext, written in Python, allows for the construction of %SALOME execution context and for application start. Each launcher creates a \c SalomeContext object, and optionally gives it a list of configuration files to describe the context:
\code
SalomeContext.__init__(configFileNames=None)
\endcode
-A launcher can also directly call the API functions to define, suppress or extend (add information) an environment variable:
+%A launcher can also directly call the API functions to define, suppress or extend (add information) an environment variable:
\code
SalomeContext.setVariable(name, value, overwrite=False)
SalomeContext.unsetVariable(name)
\section context_file_syntax Syntax of a context file
It is possible to write specific context files provided that the syntax defined
-hereinafter is respected; their analysis by the new SALOME start mechanism uses tools from the Python standard API.
+hereinafter is respected. Their analysis by the new %SALOME start mechanism uses tools from the Python standard API.
-A context file starts with a section title, and continues with the definition of different
+%A context file starts with a section title, and continues with the definition of different
context variables. The section title is a string enclosed by brackets, for example <tt>[My context]</tt>.
\subsection context_file_syntax_definition Definition
-A variable can be defined with a declaration <tt>variable=value</tt>:
+%A variable can be defined with a declaration <tt>variable=value</tt>:
\code
SALOME_PREREQUISITES=salome/prerequisites/install
\endcode
\subsection context_file_syntax_substitution Substitution
-A variable can be defined relative to another one; this substitution corresponds to the syntax <tt>%(variable)s</tt>:
+%A variable can be defined relative to another one; this substitution corresponds to the syntax <tt>%(variable)s</tt>:
\code
QTDIR=${HOME}/%(SALOME_PREREQUISITES)s/Qt-484
\endcode
ADD_TO_PYTHONPATH: %(PYQT_ROOT_DIR)s/lib/python2.7/site-packages
\endcode
+This prepends environment variables with user paths.
+
\subsection context_file_syntax_unset Unset
-A variable can be unset with <tt>UNSET: variable</tt>:
+%A variable can be unset with <tt>UNSET: variable</tt>:
\code
UNSET: LD_LIBRARY_PATH PTHREAD_ROOT_DIR
\endcode
