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.3.0 for the 7.3.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.3.0/bin/salome for the version
 132           7.3.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.3.0 for KERNEL module of SALOME version 7.3.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
 343           * YACS -> KERNEL, GUI
 344           * PARAVIS -> KERNEL, GUI, MED
 345           * HEXABLOCK -> KERNEL, GUI, GEOM
 346           * HOMARD -> KERNEL, GUI, GEOM, SMESH
 347           * JOBMANAGER -> KERNEL, GUI
 348
 349           SMESH plugins:
 350
 351           * NETGENPLUGIN -> KERNEL, GUI, GEOM, SMESH
 352           * GHS3DPLUGIN -> KERNEL, GUI, GEOM, SMESH
 353           * GHS3DPRLPLUGIN -> KERNEL, GUI, GEOM, SMESH
 354           * BLSURFPLUGIN -> KERNEL, GUI, GEOM, SMESH
 355           * HexoticPLUGIN -> KERNEL, GUI, GEOM, SMESH, BLSURFPLUGIN
 356           * HEXABLOCKPLUGIN -> KERNEL, GUI, GEOM, SMESH, HEXABLOCK
 357
 358           Sample modules:
 359
 360           * COMPONENT -> KERNEL, MED
 361           * CALCULATOR -> KERNEL, MED
 362           * PYCALCULATOR -> KERNEL, MED
 363           * HELLO -> KERNEL, GUI
 364           * PYHELLO -> KERNEL, GUI
 365           * LIGHT -> KERNEL, GUI
 366           * PYLIGHT -> KERNEL, GUI
 367           * ATOMIC -> KERNEL, GUI
 368           * ATOMGEN -> KERNEL, GUI
 369           * ATOMSOLV -> KERNEL, GUI, ATOMGEN
 370           * RANDOMIZER -> KERNEL
 371           * SIERPINSKY -> KERNEL, GUI, RANDOMIZER, SMESH
 372
 373           Other:
 374
 375           * DOCUMENTATION -> no dependencies
 376
 377           Note: SMESH plugins and sample modules are optional. You may skip
 378           compiling them if you do not plan to use NETGEN and/or GHS3D meshing
 379           algorithms and do not want to build samples.
 380
 381           Note: Meshing plug-ins BLSURFPLUGIN, HexoticPLUGIN, GHS3DPLUGIN and
 382           GHS3DPRLPLUGIN require commercial license for the Distene
 383           meshers in runtime mode. Moreover, BLSURFPLUGIN requires
 384           blsurf product at the compilation time. Without it, the
 385           BLSURFPLUGIN meshing plugin compilation will fail. Refer
 386           to http://www.distene.com/ for more details.
 387
 388           In general, each module (except for KERNEL and GUI) is
 389           optional for SALOME. If you do not need a certain module, just do not
 390           compile or install it. But remember that some modules require others
 391           to be built first (see dependencies table above).
 392
 393           To build KERNEL module:
 394
 395           - go to installation root directory (/home/user/salome in this example):
 396
 397                cd /home/user/salome
 398
 399           - to set environment variables use bash or csh script, depending on
 400             your shell:
 401
 402                source ./env_products.csh
 403             or
 404                source ./env_products.sh
 405
 406           - create build directory for the KERNEL module:
 407
 408                mkdir KERNEL_build
 409                cd KERNEL_build
 410
 411           - create a configuration script by typing
 412
 413                ../KERNEL_SRC_7.3.0/build_configure
 414
 415           - run configure script which will check the environment and create
 416             Makefile files:
 417
 418                ../KERNEL_SRC_7.3.0/configure --prefix=/home/user/salome/KERNEL-7.3.0
 419
 420           Note, that --prefix option defines the directory where you want to
 421           install KERNEL module after 'make install' procedure. configure script
 422           also accepts a lot of other parameters (for example, to build the module
 423           in the Release mode use --disable-debug --enable-production keys).
 424           You can learn more about the configure of any modules by using --help (-h)
 425           parameter.
 426
 427           - build and install KERNEL module:
 428
 429                make
 430                make install
 431
 432           After you have completed this scenario, KERNEL module is built and
 433           installed into /home/user/salome/KERNEL-7.3.0 directory.
 434
 435           - modify your environment scripts:
 436
 437           * for bash:
 438
 439                export KERNEL_ROOT_DIR=/home/user/salome/KERNEL-7.3.0
 440
 441           * for csh:
 442
 443                setenv KERNEL_ROOT_DIR /home/user/salome/KERNEL-7.3.0
 444
 445           - then repeat this scenario for other modules you want to build taking
 446             into account the dependencies between modules (see dependencies table
 447             above).
 448
 449           Note: if the compilation fails it may be caused by bad environment.
 450           In this case you should check if the environment script that you use
 451           (salome.csh or salome.sh) contains the following lines for each module MODULE:
 452
 453           * for bash:
 454
 455                export MODULE_ROOT_DIR=/home/user/salome/<MODULE_distribution>
 456
 457           * for csh:
 458
 459                setenv MODULE_ROOT_DIR /home/user/salome/<MODULE_distribution>
 460
 461           where <MODULE_distribution> is a MODULE-7.3.0 (see above).
 462
 463      4.2. Automatic build procedure: build.csh and build.sh scripts
 464
 465           SALOME Installation Wizard includes two scripts which can be used
 466           for automatic building of SALOME modules from sources packages:
 467           build.csh and build.sh. The scripts are installed into the top-level
 468           installation directory (the same directory where env_products.[c]sh
 469           files are generated).
 470
 471           The build.csh and buils.sh scripts implement the same functionality
 472           and support the same set of options, but for different shells.
 473           Use build.csh script for csh and build.sh for bash.
 474           The description below refers to both scripts.
 475
 476           To use the script just install SALOME sources packages with the
 477           Installation Wizard, then cd to the SALOME installation directory
 478           and type:
 479
 480                ./build.csh
 481
 482           By default, build.csh builds and installs all SALOME
 483           modules. All modules are installed to the INSTALL subfolder
 484           of the current directory. If you need to change the installation
 485           directory, you can use -p <prefix> option where <prefix> is the
 486           directory SALOME modules should be installed to.
 487
 488           If you want to build only some subset of SALOME modules,
 489           just pass them as parameters, e.g.:
 490
 491                ./build.csh -p /home/user/salome KERNEL MED GEOM
 492
 493           The script also provides other options which specify compiling and
 494           installation parameters. You can learn about these options by using
 495           -h key:
 496
 497                ./build.csh -h
 498
 499           When you run build.csh for the first time it is not necessary to pass
 500           -b or -c parameters. The script detects if build procedure has not yet
 501           been performed and in this case runs build_configure, configure scripts
 502           automatically.
 503
 504           Note: to avoid collisions it is recommended not to install
 505           SALOME binaries packages with Installation Wizard if you plan to build
 506           SALOME modules from sources packages or to edit/comment all rows
 507           in env_products.csh file concerning binaries packages.
 508
 509           Note: use -d option carefully because in this case the script removes
 510           the existing (previously installed) SALOME modules.
 511
 512           Note: build.(c)sh scripts do not modify the environment files
 513           (env_products.csh, etc). You should do it by yourself.
 514
 515      4.3. Build SALOME using cmake
 516
 517           Some (but not all) SALOME modules can be built using
 518           cmake. If you want to learn what modules can be built with
 519           cmake, just check the root source directory and look for
 520           CMakeLists.txt file or build_cmake script.
 521
 522           This paragraph describes the steps that should be done in
 523           order to build SALOME modules using cmake.
 524
 525           For example, to build KERNEL module:
 526
 527           - go to installation root directory (/home/user/salome in this example):
 528
 529                cd /home/user/salome
 530
 531           - to set environment variables use bash or csh script, depending on
 532             your shell:
 533
 534                source ./env_products.csh
 535             or
 536                source ./env_products.sh
 537
 538           - generate CMakeLists.txt files:
 539
 540                cd KERNEL_SRC_7.3.0
 541                ./build_cmake
 542                cd ..
 543
 544           Note, that this step is not required for PARAVIS module,
 545           since it is already supplied with the CMakeLists.txt
 546           files. For other modules, build_cmake script generates
 547           CMakeLists.txt files from the Makefile.am files.
 548
 549           - create build directory for the KERNEL module:
 550
 551                mkdir KERNEL_build
 552                cd KERNEL_build
 553
 554           - run cmake
 555
 556                cmake -DCMAKE_INSTALL_PREFIX=/home/user/salome/KERNEL-7.3.0 ../KERNEL_SRC_7.3.0
 557
 558           Note, that -DCMAKE_INSTALL_PREFIX option defines the directory where you want to
 559           install KERNEL module after 'make install' procedure. You
 560           can supply additional options to the cmake (for example, to
 561           build the module in the Release mode use -DCMAKE_BUILD_TYPE=Release option).
 562
 563           - build and install KERNEL module:
 564
 565                make
 566                make install
 567
 568           After you have completed this scenario, KERNEL module is built and
 569           installed into /home/user/salome/KERNEL-7.3.0 directory.
 570
 571           - modify your environment scripts:
 572
 573           * for bash:
 574
 575                export KERNEL_ROOT_DIR=/home/user/salome/KERNEL-7.3.0
 576
 577           * for csh:
 578
 579                setenv KERNEL_ROOT_DIR /home/user/salome/KERNEL-7.3.0
 580
 581 ================================================================================