doc/salome/salome_command.dox

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