From 0471e532d0a0620ebaf0d9d723edb111dc1db8c0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?C=C3=A9dric=20Aguerre?= Date: Wed, 9 Sep 2015 13:56:06 +0200 Subject: [PATCH] update doc and usage --- bin/launchConfigureParser.py | 13 ++++-- bin/runSalome.py | 4 +- bin/salomeContext.py | 25 +++++----- bin/setenv.py | 8 ++-- doc/salome/salome_command.dox | 87 ++++++++++++++++++++++++++++------- 5 files changed, 99 insertions(+), 38 deletions(-) diff --git a/bin/launchConfigureParser.py b/bin/launchConfigureParser.py index 2d34b48e2..2c91b69d1 100755 --- a/bin/launchConfigureParser.py +++ b/bin/launchConfigureParser.py @@ -496,7 +496,7 @@ def store_boolean (option, opt, value, parser, *args): 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 @@ -831,9 +831,12 @@ def CreateOptionParser (theAdditionalOptions=None): 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) @@ -849,7 +852,7 @@ Python file arguments, if any, must be comma-separated (without blank characters 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 "Config" (SalomeAppConfig) which can @@ -889,7 +892,7 @@ def get_env(theAdditionalOptions=None, appname=salomeappname, cfgname=salomecfgn ############################ # parse command line options - pars = CreateOptionParser(theAdditionalOptions) + pars = CreateOptionParser(theAdditionalOptions, exeName=exeName) (cmd_opts, cmd_args) = pars.parse_args(sys.argv[1:]) ############################ diff --git a/bin/runSalome.py b/bin/runSalome.py index 29b915751..50310e9d6 100755 --- a/bin/runSalome.py +++ b/bin/runSalome.py @@ -742,7 +742,7 @@ def no_main(): # ----------------------------------------------------------------------------- -def main(): +def main(exeName=None): """Salome launch as a main application""" # define folder to store omniorb config (initially in virtual application folder) @@ -754,7 +754,7 @@ def main(): sys.exit(1) from salome_utils import getHostName - args, modules_list, modules_root_dir = setenv.get_config() + args, modules_list, modules_root_dir = setenv.get_config(exeName=exeName) print "runSalome running on %s" % getHostName() kill_salome(args) diff --git a/bin/salomeContext.py b/bin/salomeContext.py index 545e92979..7a89e9666 100644 --- a/bin/salomeContext.py +++ b/bin/salomeContext.py @@ -38,17 +38,20 @@ Usage: salome [command] [options] [--config=] 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 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 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. @@ -336,7 +339,7 @@ class SalomeContext: # Initialize SALOME environment sys.argv = ['runSalome'] + args import setenv - setenv.main(True) + setenv.main(True, exeName="salome start") import runSalome runSalome.runSalome() diff --git a/bin/setenv.py b/bin/setenv.py index 154829513..e844d0eb5 100755 --- a/bin/setenv.py +++ b/bin/setenv.py @@ -78,7 +78,7 @@ def get_lib_dir(): # ----------------------------------------------------------------------------- -def get_config(silent=False): +def get_config(silent=False, exeName=None): """ Get list of modules, paths. @@ -95,7 +95,7 @@ def get_config(silent=False): #*** o_j = optparse.Option("-j", "--join", action="store_true", dest="join", help=help_str) import launchConfigureParser - args = launchConfigureParser.get_env() + args = launchConfigureParser.get_env(exeName=exeName) #*** Test additional option #*** args = launchConfigureParser.get_env([o_j]) @@ -242,8 +242,8 @@ def set_env(args, modules_list, modules_root_dir, silent=False): # ----------------------------------------------------------------------------- -def main(silent=False): - args, modules_list, modules_root_dir = get_config(silent=silent) +def main(silent=False, exeName=None): + args, modules_list, modules_root_dir = get_config(silent=silent, exeName=exeName) set_env(args, modules_list, modules_root_dir, silent=silent) return args diff --git a/doc/salome/salome_command.dox b/doc/salome/salome_command.dox index dd52d38fd..2d2387417 100644 --- a/doc/salome/salome_command.dox +++ b/doc/salome/salome_command.dox @@ -13,16 +13,29 @@ A launcher is a Python script that creates an execution context then starts SALO \section salome_launcher The salome command Usage of \c salome command is: \code - salome [command] [options] [--config=file1,...,filen] + salome [command] [options] [--config=] [--extra_env=] \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 \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 @@ -31,11 +44,14 @@ 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 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 --extra_env 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 --config 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 --config 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. @@ -50,11 +66,10 @@ a .cfg extension, for example: 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 script.py args: arg1, arg2, ..., argn +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 script.py args: arg1, arg2, ..., argn The script parameters must be separated by commas and no spaces are allowed (except between the script name and the beginning of its parameters). @@ -63,13 +78,39 @@ For example, the following call will run sequentially three scripts, which will 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 -p 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 -- [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 -p PORT, -m MACHINE, -d DIRECTORY and -u USER must be provided. Moreover syntax out:res1,res2,... 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 myself connects to remotemachine to run the script concatenate.py in a SALOME instance running on port 2810; 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 def main(args) function to sequentially execute the following operations: @@ -83,12 +124,26 @@ initialize(currentPath, launcherFile) - 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) -- 2.39.2