doc/salome/salome_command.dox

   1 /*!
   2   \page salome_command salome command
   3
   4 To start SALOME a new approach is proposed, based on \ref SALOME_Application. The underlying mechanism aims at:
   5 -# Unifying start commands\n
   6 Unix Shell scripts like runAppli, runSession and runConsole are replaced by a unique Python command named \b salome.
   7 -# Handle execution context\n
   8 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.
   9 -# Promote creation of custom start commands (launchers)\n
  10 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.
  11
  12
  13 \section salome_launcher The salome command
  14 Usage of \c salome command is:
  15 \code
  16    salome [command] [options] [--config=<file,folder,...>] [--extra_env=<file,folder,...>]
  17 \endcode
  18
  19 Commands are:
  20 - \c start \n
  21 Start a new SALOME instance.
  22 - \c context \n
  23 Initialize SALOME context. Current environment is extended.
  24 - \c shell \n
  25 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.
  26 - \c connect \n
  27 Connect a Python console to the active SALOME instance.
  28 - \c kill <port(s)> \n
  29 Terminate SALOME instances running on given ports for current user. Port numbers must be separated by blank characters.
  30 - \c killall \n
  31 Terminate *all* SALOME running instances for current user ; do not start a new one.
  32 - \c test \n
  33 Run SALOME tests.
  34 - \c info \n
  35 Display some information about SALOME.
  36 - \c help \n
  37 Show this message.
  38
  39
  40 To start an application, use \code salome start \endcode
  41 This command is equivalent to runAppli. It accepts the same options that can be listed using \code salome start --help \endcode
  42
  43 To initialize an environment, use \code salome shell \endcode
  44 This command is equivalent to runSession. It accepts the same options that can be listed using \code salome shell --help \endcode
  45
  46 To connect a Python console, use \code salome connect \endcode
  47 There is no options to this command. It asks user which SALOME instance to connect to.
  48
  49
  50 \section batch_files Batch files that set extra environment
  51 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.
  52
  53 \section context_files Context files management
  54 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.
  55
  56 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.
  57
  58 It is possible to add context files in the env.d folder; the strategy followed by \c salome
  59 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
  60 a .cfg extension, for example:
  61 -# Context1.cfg : taken into account because it has a .cfg extension.
  62 -# Context2.cfg : taken into account because it has a .cfg extension.
  63 -# Context2.sh : not taken into account because Context2.cfg exists.
  64 -# Context3.sh : considered because Context3.cfg does not exist.
  65
  66 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.
  67
  68
  69 \section several_scripts_multiple_args Run several scripts with multiple arguments
  70 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.
  71
  72 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>
  73
  74 The script parameters must be separated by commas and no spaces are allowed (except
  75 between the script name and the beginning of its parameters).
  76 For example, the following call will run sequentially three scripts, which will wait 5 seconds, say hello, and calculate 1 +2 +3:
  77 \code
  78 salome shell –p 2811 wait.py args:5 hello.py add.py args:1,2,3
  79 \endcode
  80
  81 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.
  82 The syntax is \code salome shell -- <program> [options] [arguments] \endcode
  83 For example:
  84 \code
  85        salome shell -- ls -l *.py
  86        salome shell -- python -tt hello.py
  87 \endcode
  88
  89 \section handling_concurrency Handling concurrent starts
  90 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.
  91
  92 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.
  93
  94 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):
  95 \code
  96 salome start -t --ns-port-log=${WORK_DIR}/session.log
  97 salome shell -p `cat ${WORK_DIR}/session.log` ${SALOME_APPLI_FOLDER}/bin/salome/waitContainers.py # may be optional
  98 salome shell -p `cat ${WORK_DIR}/session.log` ${BASE_DIR}/hello.py
  99 salome kill `cat ${WORK_DIR}/session.log`
 100 \endcode
 101
 102 \section remote_calls Remote calls
 103 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.
 104 For example:
 105 \code
 106        salome shell -m remotemachine -p 2810 -u myself -d /full/path/to/salome concatenate.py args:file1.txt,file2.txt out:result.txt
 107 \endcode
 108 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.
 109 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.
 110
 111
 112 \section write_launcher How to write a launcher
 113 A launcher is a Python module that contains a single <tt>def main(args)</tt> function to sequentially execute the following operations:
 114 - Detect application path
 115 \code
 116 currentPath = os.path.dirname( os.path.abspath( __file__ ) )
 117 launcherFile = os.path.basename(__file__)
 118 from salome_starter import initialize
 119 initialize(currentPath, launcherFile)
 120 \endcode
 121 - Identify configuration (context) files
 122 \code
 123 from salomeContextUtils import getConfigFileNames
 124 configFileNames, extraEnv, args, unexisting = getConfigFileNames(args, checkExistence=True)
 125 \endcode
 126 extraEnv variable
 127 - Create a context
 128 \code
 129 context = SalomeContext(configFileNames)
 130 \endcode
 131 The execution context can be set or overloaded using \ref salome_api, for example:
 132 \code
 133 # context.addToPath('mypath')
 134 # context.addToLdLibraryPath('myldlibrarypath')
 135 # context.addToPythonPath('mypythonpath')
 136 # context.setVariable('myvarname', 'value')
 137 \endcode
 138 - Initializing extra environment variables parsed from batch files:
 139 \code
 140 if extraEnv:
 141   for key,val in extraEnv.items():
 142     context.addToVariable(key,val)
 143 \endcode
 144 - Run SALOME
 145 \code
 146 (out, err), returncode = context.runSalome(args)
 147 \endcode
 148
 149 This module is generally used as a script, run from a shell command line. It thus contains the directive:
 150 \code
 151 if __name__ == "__main__":
 152   args = sys.argv[1:]
 153   main(args)
 154 #
 155 \endcode
 156
 157 Finally the module can be called from another script, for example a test script. Considering a Python variable \c path_to_launcher that identifies the absolute path to a launcher, one can write:
 158 \code
 159 appli_dir = os.path.dirname(path_to_launcher)
 160 sys.path[:0] = [os.path.join(appli_dir, "bin", "salome", "appliskel")]
 161 self.SALOME = imp.load_source("SALOME", os.path.join(appli_dir,"salome"))
 162 try:
 163   self.SALOME.main(["shell", "hello.py"])
 164 except SystemExit, e:
 165   if str(e) != '0':
 166     logging.error(e)
 167 \endcode
 168
 169
 170 \section salome_api The API
 171 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:
 172 \code
 173 SalomeContext.__init__(configFileNames=None)
 174 \endcode
 175
 176 A launcher can also directly call the API functions to define, suppress or extend (add information) an environment variable:
 177 \code
 178 SalomeContext.setVariable(name, value, overwrite=False)
 179 SalomeContext.unsetVariable(name)
 180 SalomeContext.addToVariable(name, value, separator=os.pathsep)
 181 \endcode
 182
 183 The \c addToVariable function consists in prefixing the variable name with the given value inserting a separator between the two items.
 184
 185 Unix system variables PATH, LD_LIBRARY_PATH (DYLD_LIBRARY PATH for BSD) and PYTHONPATH can only be extended:
 186 \code
 187 SalomeContext.addToPath(value)
 188 SalomeContext.addToLdLibraryPath(value)
 189 SalomeContext.addToDyldLibraryPath(value)
 190 SalomeContext.addToPythonPath(value)
 191 \endcode
 192
 193 Once the context is created, the application is started:
 194 \code
 195 SalomeContext.runSalome(args)
 196 \endcode
 197
 198 The \c args list corresponds to commands and options given to \c salome launcher.
 199
 200
 201 \section context_file_syntax Syntax of a context file
 202 It is possible to write specific context files provided that the syntax defined
 203 hereinafter is respected; their analysis by the new SALOME start mechanism uses tools from the Python standard API.
 204
 205 A context file starts with a section title, and continues with the definition of different
 206 context variables. The section title is a string enclosed by brackets, for example <tt>[My context]</tt>.
 207
 208 \subsection context_file_syntax_definition Definition
 209 A variable can be defined with a declaration <tt>variable=value</tt>:
 210 \code
 211 SALOME_PREREQUISITES=salome/prerequisites/install
 212 \endcode
 213
 214 \subsection context_file_syntax_substitution Substitution
 215 A variable can be defined relative to another one; this substitution corresponds to the syntax <tt>%(variable)s</tt>:
 216 \code
 217 QTDIR=${HOME}/%(SALOME_PREREQUISITES)s/Qt-484
 218 \endcode
 219 In this example QTDIR will equal ${HOME}/salome/prerequisites/install/Qt-484
 220
 221 \subsection context_file_syntax_system System variables
 222 Specific system variables such as PATH, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH and PYTHONPATH are extended with <tt>ADD_TO_variable: valeur</tt>.
 223 \code
 224 ADD_TO_PATH: %(QTDIR)s/bin
 225 ADD_TO_LD_LIBRARY_PATH: %(QTDIR)s/lib
 226 ADD_TO_PYTHONPATH: %(PYQT_ROOT_DIR)s/lib/python2.7/site-packages
 227 \endcode
 228
 229 \subsection context_file_syntax_unset Unset
 230 A variable can be unset with <tt>UNSET: variable</tt>:
 231 \code
 232 UNSET: LD_LIBRARY_PATH PTHREAD_ROOT_DIR
 233 \endcode
 234
 235 \n
 236
 237 */