for attribute in args:
setattr(parser.values, attribute, value)
-def CreateOptionParser (theAdditionalOptions=None):
+def CreateOptionParser (theAdditionalOptions=None, exeName=None):
if theAdditionalOptions is None:
theAdditionalOptions = []
# GUI/Terminal. Default: GUI
opt_list += theAdditionalOptions
- a_usage = """%prog [options] [STUDY_FILE] [PYTHON_FILE [args] [PYTHON_FILE [args]...]]
+ if not exeName:
+ exeName = "%prog"
+
+ a_usage = """%s [options] [STUDY_FILE] [PYTHON_FILE [args] [PYTHON_FILE [args]...]]
Python file arguments, if any, must be comma-separated (without blank characters) and prefixed by "args:" (without quotes), e.g. myscript.py args:arg1,arg2=val,...
-"""
+"""%exeName
version_str = "Salome %s" % version()
pars = optparse.OptionParser(usage=a_usage, version=version_str, option_list=opt_list)
args = {}
#def get_env():
#args = []
-def get_env(theAdditionalOptions=None, appname=salomeappname, cfgname=salomecfgname):
+def get_env(theAdditionalOptions=None, appname=salomeappname, cfgname=salomecfgname, exeName=None):
###
# Collect launch configuration files:
# - The environment variable "<appname>Config" (SalomeAppConfig) which can
############################
# parse command line options
- pars = CreateOptionParser(theAdditionalOptions)
+ pars = CreateOptionParser(theAdditionalOptions, exeName=exeName)
(cmd_opts, cmd_args) = pars.parse_args(sys.argv[1:])
############################
Commands:
=========
- start Starts a SALOME session (through virtual application)
- context Initializes SALOME context.
- shell Initializes SALOME context, and executes scripts passed
- as command arguments
- connect Connects a Python console to the active SALOME session
- kill <port(s)> Terminate SALOME session running on given ports for current user
- Port numbers must be separated by blank characters
- killall Kill *all* SALOME running sessions for current user
+ start Start a new SALOME instance.
+ 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
+ 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.
+ Port numbers must be separated by blank characters.
+ killall Terminate *all* SALOME running instances for current user.
+ Do not start a new one.
test Run SALOME tests.
- info Display some information about SALOME
- help Show this message
+ info Display some information about SALOME.
+ help Show this message.
If no command is given, default to start.
# Initialize SALOME environment
sys.argv = ['runSalome'] + args
import setenv
- setenv.main(True)
+ setenv.main(True, exeName="salome start")
import runSalome
runSalome.runSalome()
\section salome_launcher The salome command
Usage of \c salome command is:
\code
- salome [command] [options] [--config=file1,...,filen]
+ salome [command] [options] [--config=<file,folder,...>] [--extra_env=<file,folder,...>]
\endcode
Commands are:
--# \c start: start a new SALOME application. This is the default command.
--# \c shell: initialize SALOME environment, attached to the last created execution context if any. User works in a Shell terminal; SALOME environment is set but application is not started.
--# \c connect: connect a Python console to an active SALOME session.
--# \c killall: terminates all SALOME sessions (do not start a new one).
--# \c info: displays Python and SALOME versions.
--# \c help: obvious...
+- \c start \n
+Start a new SALOME instance.
+- \c context \n
+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.
+- \c connect \n
+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.
+- \c killall \n
+Terminate *all* SALOME running instances for current user ; do not start a new one.
+- \c test \n
+Run SALOME tests.
+- \c info \n
+Display some information about SALOME.
+- \c help \n
+Show this message.
+
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
This command is equivalent to runSession. It accepts the same options that can be listed using \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 session to connect to.
+There is no options to this command. It asks user which SALOME instance to connect to.
+
+\section batch_files Batch files that set extra environment
+The <tt>--extra_env</tt> option is used to identify a list of batch files (or directories containing such files) that must be considered to create the SALOME execution context. Typically on linux these files are shell scripts that modify the global environment. The salome command determines environment changes implied by running these files to initialize SALOME context. Note that this functionality is not the recommanded way to set SALOME context ; it is provided for backward compatibility and convenience ; prefer \ref context_files solution.
\section context_files Context files management
-The <tt>--config</tt> option is used to identify the list of configuration files 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 <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.
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.
-\section new_features New features
-\subsection new_features_scripts Run several scripts with multiple arguments
+\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 new \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 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 script parameters must be separated by commas and no spaces are allowed (except
between the script name and the beginning of its parameters).
salome shell –p 2811 wait.py args:5 hello.py add.py args:1,2,3
\endcode
-\subsection new_features_concurrency Handle concurrent starts
-In the previous command, the <tt>-p</tt> option is used to specify a TCP port number on which the CORBA name server of each SALOME application will connect. In an attempt to explain it simply, we are talking about a technique 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.
+The command \c salome \c shell allows a double dash syntax (- -) to indicate an extra command to be run "as is". It allows calling a extern program or system command having options and arguments that contain simple dash (-) characters.
+The syntax is \code salome shell -- <program> [options] [arguments] \endcode
+For example:
+\code
+ salome shell -- ls -l *.py
+ 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.
-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 may be conflicting, and the same port may be assigned to several applications. To resolve this situation, a Python object named \c Portmanager is proposed (Linux only). In SALOME 7, this object is available when activating a specific compilation flag of KERNEL module:
+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 (Linux only). In SALOME 7, this object is available when activating a specific compilation flag of KERNEL module:
- For gcc: -DWITH_PORTMANAGER
- With CMake: SALOME_USE_PORTMANAGER=ON
+Since SALOME 7.5.0 this flag is switched ON by default.
+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):
+\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 shell -p `cat ${WORK_DIR}/session.log` ${BASE_DIR}/hello.py
+salome kill `cat ${WORK_DIR}/session.log`
+\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.
+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.
+
\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:
- Identify configuration (context) files
\code
from salomeContextUtils import getConfigFileNames
-configFileNames, args, unexisting = getConfigFileNames(args, checkExistence=True
+configFileNames, extraEnv, args, unexisting = getConfigFileNames(args, checkExistence=True)
\endcode
+extraEnv variable
- Create a context
\code
context = SalomeContext(configFileNames)
\endcode
+The execution context can be set or overloaded using \ref salome_api, for example:
+\code
+# context.addToPath('mypath')
+# context.addToLdLibraryPath('myldlibrarypath')
+# context.addToPythonPath('mypythonpath')
+# context.setVariable('myvarname', 'value')
+\endcode
+- Initializing extra environment variables parsed from batch files:
+\code
+if extraEnv:
+ for key,val in extraEnv.items():
+ context.addToVariable(key,val)
+\endcode
- Run SALOME
\code
(out, err), returncode = context.runSalome(args)
