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