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_6.3.0 for the 6.3.0 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_6.3.0/bin/salome for the version
 131           6.3.0) 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,MED,YACS"/>
 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 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/user/salome directory. The name of each module
 320           sources directory depends on the version of the platform, for example,
 321           KERNEL_SRC_6.3.0 for KERNEL module of SALOME version 6.3.0.
 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           * YACS -> KERNEL, GUI
 335
 336           SMESH plugins:
 337
 338           * NETGENPLUGIN -> KERNEL, GUI, MED, GEOM, SMESH
 339           * GHS3DPLUGIN -> KERNEL, GUI, MED, GEOM, SMESH
 340           * GHS3DPRLPLUGIN -> KERNEL, GUI, MED, GEOM, SMESH
 341           * HexoticPLUGIN -> KERNEL, GUI, MED, GEOM, SMESH
 342           * BLSURFPLUGIN -> KERNEL, GUI, MED, GEOM, 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, GUI
 351           * LIGHT -> KERNEL, GUI
 352           * PYLIGHT -> KERNEL, GUI
 353           * RANDOMIZER -> KERNEL, GUI
 354           * SIERPINSKY -> KERNEL, GUI, MED, VISU, RANDOMIZER
 355
 356           Note: SMESH plugins and sample modules are optional. You may skip
 357           compiling them if you do not plan to use NETGEN and/or GHS3D meshing
 358           algorithms and do not want to build samples.
 359
 360           Note: Meshing plug-ins BLSURFPLUGIN, HexoticPLUGIN and
 361           GHS3DPRLPLUGIN require commercial license for the Distene
 362           meshers in runtime mode. Moreover, BLSURFPLUGIN requires
 363           blsurf product at the compilation time. Without it, the
 364           BLSURFPLUGIN meshing plugin compilation will fail. Refer
 365           to http://www.distene.com/ for more details.
 366
 367           In general, each module (except for KERNEL and GUI, of course) is
 368           optional for SALOME. If you do not need a certain module, just do not
 369           compile or install it. But remember that some modules require others
 370           to be built first (see dependencies table above).
 371
 372           To build KERNEL module:
 373
 374           - go to installation root directory (/home/user/salome in this example):
 375
 376                cd /home/user/salome
 377
 378           - to set environment variables use bash or csh script, depending on
 379             your shell:
 380
 381                source ../env_products.csh
 382             or
 383                source ../env_products.sh
 384
 385           - create build directory for the KERNEL module:
 386
 387                mkdir KERNEL_build
 388                cd KERNEL_build
 389
 390           - create a configuration script by typing
 391
 392                ../KERNEL_SRC_6.3.0/build_configure
 393
 394           - run configure script which will check the environment and create
 395             Makefile files:
 396
 397                ../KERNEL_SRC_6.3.0/configure --prefix=/home/user/salome/KERNEL-6.3.0
 398
 399           Note, that --prefix option defines the directory where you want to
 400           install KERNEL module after 'make install' procedure. configure script
 401           also accepts a lot of other parameters (for example, to build the module
 402           in the optimized mode use --disable-debug --enable-production keys).
 403           You can learn more about the configure of any modules by using --help (-h)
 404           parameter.
 405
 406           - build and install KERNEL module:
 407
 408                make
 409                make install
 410
 411           After you have completed this scenario, KERNEL module is built and
 412           installed into /home/user/salome/KERNEL-6.3.0 directory.
 413
 414           - modify your environment scripts:
 415
 416           * for bash:
 417
 418                export KERNEL_ROOT_DIR=/home/user/salome/KERNEL-6.3.0
 419
 420           * for csh:
 421
 422                setenv KERNEL_ROOT_DIR /home/user/salome/KERNEL-6.3.0
 423
 424           - then repeat this scenario for other modules you want to build taking
 425             into account the dependencies between modules (see dependencies table
 426             above).
 427
 428           Note: if the compilation fails it may be caused by bad environment.
 429           In this case you should check if the environment script that you use
 430           (salome.csh or salome.sh) contains the following lines for each module MODULE:
 431
 432           * for bash:
 433
 434                export MODULE_ROOT_DIR=/home/user/salome/<MODULE_distribution>
 435
 436           * for csh:
 437
 438                setenv MODULE_ROOT_DIR /home/user/salome/<MODULE_distribution>
 439
 440           where <MODULE_distribution> is a MODULE-6.3.0 (see above).
 441
 442      4.2. Automatic build procedure: build.csh and build.sh scripts
 443
 444           SALOME Installation Wizard includes two scripts which can be used
 445           for automatic building of SALOME modules from sources packages:
 446           build.csh and build.sh. The scripts are installed into the top-level
 447           installation directory (the same directory where env_products.[c]sh
 448           files are generated).
 449
 450           The build.csh and buils.sh scripts implement the same functionality
 451           and support the same set of options, but for different shells.
 452           Use build.csh script for csh and build.sh for bash.
 453           The description below refers to both scripts.
 454
 455           To use the script just install SALOME sources packages with the
 456           Installation Wizard, then cd to the SALOME installation directory
 457           and type:
 458
 459                ./build.csh
 460
 461           By default, build.csh builds and installs all SALOME
 462           modules. All modules are installed to the INSTALL subfolder
 463           of the current directory. If you need to change the installation
 464           directory, you can use -p <prefix> option where <prefix> is the
 465           directory SALOME modules should be installed to.
 466
 467           If you want to build only some subset of SALOME modules,
 468           just pass them as parameters, e.g.:
 469
 470                ./build.csh -p /home/user/salome KERNEL MED GEOM
 471
 472           The script also provides other options which specify compiling and
 473           installation parameters. You can learn about these options by using
 474           -h key:
 475
 476                ./build.csh -h
 477
 478           When you run build.csh for the first time it is not necessary to pass
 479           -b or -c parameters. The script detects if build procedure has not yet
 480           been performed and in this case runs build_configure, configure scripts
 481           automatically.
 482
 483           Note: to avoid collisions it is recommended not to install
 484           SALOME binaries packages with Installation Wizard if you plan to build
 485           SALOME modules from sources packages or to edit/comment all rows
 486           in env_products.csh file concerning binaries packages.
 487
 488           Note: use -d option carefully because in this case the script removes
 489           the existing (previously installed) SALOME modules.
 490
 491           Note: build.(c)sh scripts do not modify the environment files
 492           (env_products.csh, etc). You should do it by yourself.
 493
 494 ================================================================================