README

   1 ================================================================================
   2                                      README
   3                            SALOME Installation Wizard
   4 ================================================================================
   5
   6   Contents of this file:
   7
   8   1. Running of the Installation Wizard
   9
  10   2. Running of SALOME
  11      2.1. Setting of the environment for SALOME
  12      2.2. Launching of SALOME
  13
  14   3. Installation notes
  15      3.1. Time required for the installation
  16      3.2. Log files
  17      3.3. Testing of the installed SALOME platform
  18
  19   4. How to build SALOME modules from sources
  20      4.1. General procedure
  21      4.2. Automatic build procedure: build.csh script
  22
  23 ================================================================================
  24
  25   1. Running of the Installation Wizard
  26
  27      The Installation Wizard can be launched in two modes: GUI and batch.
  28      The root directory of the Installation Wizard contains Python
  29      script runInstall. To run the Installation Wizard just type
  30      runInstall in the terminal window:
  31
  32      [ python ] runInstall [<options>]
  33
  34      Without any option this script will launch the SALOME Installation
  35      Wizard in the default mode (GUI) with the default installation
  36      parameters. The default mode can be overridden by using command
  37      line options. Each option has short and long notations:
  38
  39      -g / --gui
  40
  41      Runs the Installation Wizard in the GUI mode (this is the default
  42      mode).
  43
  44      -b / --batch
  45
  46      Runs the Installation Wizard in command-line mode.
  47
  48      -f FILE / --file=FILE
  49
  50      Defines the XML configuration file to be used by the Installation Wizard.
  51      If the appropriate file is not found, the warning message is shown.
  52      If this option is not used then the installation script tries to
  53      define the Linux version and use the corresponding XML file.
  54      For example, for the Linux Mandriva 2006.0 the config_Mandriva_2006.0.xml
  55      file will be used by default.
  56
  57      -d DIR / --target=DIR
  58
  59      Defines the target directory for SALOME platform installation.
  60      If used, this option overrides the default target directory,
  61      indicated in the configuration XML file (usually
  62      ${HOME}/salome_<version>).
  63
  64      -t DIR / --tmp=DIR
  65
  66      Defines the directory for temporary files. If used, this
  67      option overrides the default temporary directory, indicated in
  68      the configuration xml file (usually /tmp).
  69
  70      -a / --all-from-sources
  71
  72      Forces all products to be installed from sources including SALOME
  73      modules. If this option is used all the default installation modes
  74      are ignored.
  75
  76      -s / --single-directory
  77
  78      Install all SALOME binaries packages to one directory (SALOME_<version>,
  79      where <version> is SALOME version).
  80      Note: this option is ignored when --all-from-sources (-a) option is used.
  81
  82      -h / --help
  83
  84      Prints help information about available options.
  85
  86      -v / --version
  87
  88      Prints version information (Note: this is the version number of
  89      the Installation Wizard, not of the SALOME platform).
  90
  91      For more detailed information about the Installation Wizard refer to the
  92      readme.html file in the doc directory.
  93
  94 ================================================================================
  95
  96   2. Running of SALOME
  97
  98      This section describes how to run SALOME platform after its installation
  99      with the Installation Wizard.
 100
 101      2.1. Setting of the environment for SALOME
 102
 103           Installation Wizard creates some environment files to simplify
 104           the procedure of launching SALOME. These shell scripts set all
 105           necessary environment variables for all products you have installed.
 106           These files are:
 107                * env_products.csh + env_products.sh in the target directory;
 108                  these files can be used for the launching of SALOME.
 109                * salome.csh + salome.sh in the KERNEL module's sources/binaries
 110                  root directories; these files are the copies of the
 111                  corresponding env_products.* files.
 112                * env_build.csh + env_build.sh in the target directory;
 113                  these files contain minimal environment settings necessary
 114                  to build SALOME packages from sources (see paragraph 4).
 115
 116           To set SALOME environment just type in the terminal window:
 117
 118                cd <KERNEL_ROOT_DIR>
 119                source salome.sh
 120           or
 121                cd <KERNEL_ROOT_DIR>
 122                source salome.csh
 123
 124           where <KERNEL_ROOT_DIR> is KERNEL binaries directory, e.g.
 125           KERNEL_4.1.4 for the 4.1.4 version.
 126
 127      2.2. Launching of SALOME
 128
 129           After you set environment you can start SALOME. Go to the KERNEL
 130           module's binaries directory (KERNEL_4.1.4/bin/salome for the version
 131           4.1.4) by using of 'cd' command and then type:
 132
 133                runSalome [<parameters>]
 134
 135           This will start SALOME according to the launching parameters which
 136           are described in the configuration files: SalomeApp.xml in the
 137           <GUI_ROOT_DIR>/share/salome/resources/gui folder and
 138           .SalomeApprc.<version_number> file, located in your home
 139           directory (where <version_number> is SALOME version number).
 140           If the user configuration file does not exist, it is automatically
 141           created when exiting SALOME GUI.
 142
 143           You can modify SALOME launching options by editing your
 144           ~/.SalomeApprc.<version_number> file (not all the options are
 145           listed below):
 146
 147           <section name="launch">
 148             <parameter name="gui"        value="yes"/>
 149             <parameter name="splash"     value="yes"/>
 150             <parameter name="file"       value="no"/>
 151             <parameter name="key"        value="no"/>
 152             <parameter name="interp"     value="no"/>
 153             <parameter name="logger"     value="no"/>
 154             <parameter name="xterm"      value="no"/>
 155             <parameter name="portkill"   value="no"/>
 156             <parameter name="killall"    value="no"/>
 157             <parameter name="modules"    value="GEOM,SMESH,VISU,SUPERV,MED,COMPONENT"/>
 158             <parameter name="embedded"   value="SalomeAppEngine"/>
 159             <parameter name="standalone" value="study,pyContainer,cppContainer,registry,moduleCatalog"/>
 160           </section>
 161
 162           Some parameters described in configuration file can be overridden by
 163           using of corresponding command-line options for runSalome script:
 164
 165           -t, --terminal
 166                 Launch without GUI (in the terminal mode).
 167           -g, --gui
 168                 Launch in GUI mode [default].
 169           -d <1/0>, --show-desktop=<1/0>
 170                 1 to activate GUI desktop [default], 0 to not activate
 171                 GUI desktop (Session_Server starts, but GUI is not
 172                 shown). Ignored in the terminal mode.
 173           -o, --hide-desktop
 174                 Do not activate GUI desktop (Session_Server starts,
 175                 but GUI is not shown). The same as --show-desktop=0.
 176           -b, --batch
 177                 Launch in Batch Mode. (Without GUI on batch machine)
 178           -l, --logger
 179                 Redirect messages to the CORBA collector.
 180           -f <log-file>, --log-file=<log-file>
 181                 Redirect messages to the <log-file>
 182           -u <script1,script2,...>, --execute=<script1,script2,...>
 183                 Python script(s) to be imported. Python scripts are
 184                 imported in the order of their appearance. In GUI mode
 185                 python scripts are imported in the embedded python
 186                 interpreter of current study, otherwise in an external
 187                 python interpreter
 188           -r <file>, --resources=<file>
 189                 Parse application settings from the <file> instead of
 190                 default $(HOME)/.SalomeApprc.$(version)
 191           -x, --xterm
 192                 Launch each SALOME server in own xterm console
 193           -m <module1,module2,...>, --modules=<module1,module2,...>
 194                 SALOME modules list (where <module1>, <module2> are
 195                 the names of SALOME modules which should be available
 196                 in the SALOME session)
 197           -e <server1,server2,...>, --embedded=<server1,server2,...>
 198                 CORBA servers to be launched in the Session embedded
 199                 mode. Valid values for <serverN>: registry, study,
 200                 moduleCatalog, cppContainer, SalomeAppEngine [by
 201                 default the value from the configuration files is
 202                 used]
 203           -s <server1,server2,...>, --standalone=<server1,server2,...>
 204                 CORBA servers to be launched in the standalone mode
 205                 (as separate processes). Valid values for <serverN>:
 206                 registry, study, moduleCatalog, cppContainer,
 207                 pyContainer, supervContainer [by default the value
 208                 from the configuration files is used]
 209           -p, --portkill
 210                 Kill SALOME with the current port
 211           -k, --killall
 212                 Kill all running SALOME sessions
 213           -i <N>, --interp=<N>
 214                 The number of additional external python interpreters
 215                 to run. Each additional python interpreter is run in
 216                 separate xterm session with properly set SALOME
 217                 environment
 218           -z <1/0>, --splash=<1/0>
 219                 1 to display splash screen [default], 0 to disable
 220                 splash screen. This option is ignored in the terminal
 221                 mode. It is also ignored if --show-desktop=0 option is
 222                 used.
 223           -c <1/0>, --catch-exceptions=<1/0>
 224                 1 (yes,true,on,ok) to enable centralized exception
 225                 handling [default], 0 (no,false,off,cancel) to disable
 226                 centralized exception handling.
 227           --print-port
 228                 Print free port and exit
 229           --nosave-config
 230                 Do not save current configuration
 231                         ${HOME}/.omniORB_last.cfg
 232           --pinter
 233                 Launch with interactive python console.
 234           --ns-port-log=<ns_port_log_file>
 235                 Print Naming Service Port into a user file.
 236           --gdb-session
 237                 Launch session with gdb
 238           --version
 239                 Show program's version number and exit
 240
 241           Additional launch settings are given in other sections, which refer to certain
 242           modules. For example, SMESH plugins which should be used in the SALOME launch
 243           session can be mentioned in the <SMESH> section, e.g.:
 244
 245           <section name="SMESH">
 246             <parameter name="name"       value="Mesh"/>
 247             <parameter name="icon"       value="ModuleMesh.png"/>
 248             <parameter name="plugins"    value="StdMeshers,NETGENPlugin"/>
 249           </section>
 250
 251 ================================================================================
 252
 253   3. Installation notes
 254
 255      3.1. Time required for the installation
 256
 257           Installation of all products which are necessary to build and
 258           start SALOME is a time-consuming process and needs from the user to be
 259           patient.
 260           The quickest way to install SALOME is installation from the binaries.
 261           In this mode the Installation Wizard just extracts all precompiled
 262           products from the corresponding archives (except for the products
 263           which can be installed only by compiling from sources).
 264           The installation from sources requires much more time than from
 265           binaries because in this case the Installation Wizard extracts and
 266           then builds each product using the product's own compilation
 267           procedure.
 268           The installation time also depends on the computer and platform used.
 269           For example, to install SALOME on Pentium IV-3GHz, Linux Mandriva 2006.0,
 270           time of the installation is:
 271
 272                - from binaries: ~15 minutes;
 273                - from sources: more than 24 hours.
 274
 275      3.2. Log files
 276
 277           The Installation Wizard displays the installation progress in the
 278           corresponding windows (see readme.html). The Wizard uses a temporary
 279           directory to store and build the products. During the installation
 280           it produces some log files in this directory. If you suspect that
 281           the program hangs you can check the log files. These files have names
 282           in capital letters like CONFIGURE.LOG, MAKE.LOG, MAKEINSTALL.LOG, etc.
 283
 284      3.3. Testing of installed SALOME platform
 285
 286           There is a python script which allows quickly testing all SALOME
 287           modules. This script can help to check if SALOME has been installed
 288           successfully.
 289           To test SALOME platform, run SALOME desktop (see section 2), then
 290           create a new study window (menu command 'File/New') and then type
 291           in the study's embedded python console window:
 292
 293                import salome_test
 294
 295           When running, the script loads different modules (Geometry, Mesh, Med,
 296           Post-Pro and Supervisor) and tests various functionalities of these
 297           modules. You can watch the script execution progress in the embedded
 298           python console window.
 299
 300           Note: salome_test.py scripts require SALOME samples module
 301           (SAMPLES_SRC) to be installed (this module includes a set of sample
 302           MED, Python, Supervisor graph, etc files).
 303           Environment variable DATA_DIR should point at the SALOME
 304           samples module directory.
 305
 306 ================================================================================
 307
 308   4. How to build SALOME modules from sources
 309
 310      This section describes how to build SALOME modules manually
 311      from the sources distribution provided with the Installation Wizard.
 312
 313      4.1. General procedure
 314
 315           If you want to build SALOME modules from sources, install all prerequisite
 316           products, required for the platform and SALOME modules sources.
 317           Then follow the scenario described below.
 318           In this scenario it is supposed that you have installed SALOME
 319           modules sources in the /home/salome directory. The name of each module
 320           sources directory depends on the version of the platform, for example,
 321           KERNEL_SRC_4.1.4 for KERNEL module of SALOME version 4.1.4.
 322
 323           Compilation and installation should be performed according to
 324           the dependencies between modules:
 325
 326           Main SALOME modules:
 327
 328           * KERNEL -> no dependencies
 329           * GUI -> KERNEL
 330           * GEOM -> KERNEL, GUI
 331           * MED -> KERNEL, GUI
 332           * SMESH -> KERNEL, GUI, GEOM, MED
 333           * VISU -> KERNEL, GUI, MED
 334           * SUPERV -> KERNEL, GUI
 335
 336           SMESH plugins:
 337
 338           * NETGENPLUGIN -> KERNEL, GUI, SMESH
 339           * GHS3DPLUGIN -> KERNEL, GUI, SMESH
 340           * GHS3DPRLPLUGIN -> KERNEL, GUI, SMESH
 341           * HexoticPLUGIN -> KERNEL, GUI, SMESH
 342           * BLSURFPLUGIN -> KERNEL, GUI, SMESH
 343
 344           Sample modules:
 345
 346           * COMPONENT -> KERNEL, MED
 347           * PYCALCULATOR -> KERNEL, MED
 348           * CALCULATOR -> KERNEL, MED
 349           * HELLO -> KERNEL, GUI
 350           * PYHELLO -> KERNEL
 351           * LIGHT -> KERNEL, GUI
 352           * RANDOMIZER -> KERNEL, GUI
 353           * SIERPINSKY -> KERNEL, GUI, VISU, RANDOMIZER
 354
 355           Note: SMESH plugins and sample modules are optional. You may skip
 356           compiling them if you do not plan to use NETGEN and/or GHS3D meshing
 357           algorithms and do not want to build samples.
 358
 359           In general, each module (except for KERNEL and GUI, of course) is
 360           optional for SALOME. If you do not need a certain module, just do not
 361           compile or install it. But remember that some modules require others
 362           to be built first (see dependencies table above).
 363
 364           To build KERNEL module:
 365
 366           - go to installation root directory (/home/salome in this example):
 367
 368                cd /home/salome
 369
 370           - to set environment variables use bash or csh script, depending on
 371             your shell:
 372
 373                source ../env_products.csh
 374             or
 375                source ../env_products.sh
 376
 377           - create build directory for the KERNEL module:
 378
 379                mkdir KERNEL_build
 380                cd KERNEL_build
 381
 382           - create a configuration script by typing
 383
 384                ../KERNEL_SRC_4.1.4/build_configure
 385
 386           - run configure script which will check the environment and create
 387             Makefile files:
 388
 389                ../KERNEL_SRC_4.1.4/configure --prefix=/home/salome/KERNEL_install
 390
 391           Note, that --prefix option defines the directory where you want to
 392           install KERNEL module after 'make install' procedure. configure script
 393           also accepts a lot of other parameters (for example, to build the module
 394           in the optimized mode use --disable-debug --enable-production keys).
 395           You can learn more about the configure of any modules by using --help (-h)
 396           parameter.
 397
 398           - build and (optionally) install KERNEL module:
 399
 400                make
 401                make install
 402
 403           After you have completed this scenario, KERNEL module is built and
 404           installed into /home/salome/KERNEL_install directory.
 405
 406           - modify your environment scripts:
 407
 408           * for bash:
 409
 410                export KERNEL_ROOT_DIR=/home/salome/KERNEL_install
 411             or
 412                export KERNEL_ROOT_DIR=/home/salome/KERNEL_build
 413                (if make install step was not performed).
 414
 415           * for csh:
 416
 417                setenv KERNEL_ROOT_DIR /home/salome/KERNEL_install
 418             or
 419                setenv KERNEL_ROOT_DIR /home/salome/KERNEL_build
 420                (if make install step was not performed).
 421
 422           - then repeat this scenario for other modules you want to build taking
 423             into account the dependencies between modules (see dependencies table
 424             above).
 425
 426           Note: if the compilation fails it may be caused by bad environment.
 427           In this case you should check if the environment script that you use
 428           (salome.csh or salome.sh) contains the following lines for each module MODULE:
 429
 430           * for bash:
 431
 432                export MODULE_ROOT_DIR=/home/salome/<MODULE_distribution>
 433
 434           * for csh:
 435
 436                setenv MODULE_ROOT_DIR /home/salome/<MODULE_distribution>
 437
 438           where <MODULE_distribution> is a MODULE_build or MODULE_install (see above).
 439
 440      4.2. Automatic build procedure: build.csh and build.sh scripts
 441
 442           SALOME Installation Wizard includes two scripts which can be used
 443           for automatic building of SALOME modules from sources packages:
 444           build.csh and build.sh. The scripts are installed into the top-level
 445           installation directory (the same directory where env_products.[c]sh
 446           files are generated).
 447
 448           The build.csh and buils.sh scripts implement the same functionality
 449           and support the same set of options, but for different shells.
 450           Use build.csh script for csh and build.sh for bash.
 451           The description below refers to both scripts.
 452
 453           To use the script just install SALOME sources packages with the
 454           Installation Wizard, then cd to the SALOME installation directory
 455           and type:
 456
 457                ./build.csh
 458
 459           By default, build.csh only compiles the modules but does not install them,
 460           i.e. does not perform 'make install' step.
 461           To do this, use -i option or -p <prefix> where <prefix> is the
 462           directory SALOME modules should be installed to.
 463
 464           If you want to build only some SALOME modules, just pass them as
 465           parameters, e.g.:
 466
 467                ./build.csh -i KERNEL MED GEOM
 468
 469           The script also provides other options which specify compiling and
 470           installation parameters. You can learn about these options by using
 471           -h key:
 472
 473                ./build.csh -h
 474
 475           When you run build.csh for the first time it is not necessary to pass
 476           -b, -c parameters. The script detects if build procedure has not yet
 477           been performed and in this case runs build_configure, configure scripts
 478           automatically.
 479
 480           Note: to avoid collisions it is recommended not to install
 481           SALOME binaries packages with Installation Wizard if you plan to build
 482           SALOME modules from sources packages or to edit/comment all rows
 483           in env_products.csh file concerning binaries packages.
 484
 485           Note: use -d option carefully because in this case the script removes
 486           the existing (previously installed) SALOME modules.
 487
 488           Note: please, take into your account that 'make install' step is
 489           obligatory for the KERNEL module. Build directory of KERNEL
 490           can not be indicated as KERNEL_ROOT_DIR. This is an exception
 491           for the SALOME modules. So you should use either option -i
 492           or -p of build.sch script when building KERNEL module.
 493
 494           Note: build.(c)sh scripts do not modify the environment files
 495           (env_products.csh, etc). You should do it by yourself.
 496
 497 ================================================================================