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 opstions this script will launch the SALOME Installation
  35      Wizard in the default mode (GUI). The default mode can be
  36      overriden by using command line options. Each option has short
  37      and long notations:
  38
  39      -g / --gui
  40
  41      Runs the Installation Wizard in the GUI mode (this is 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      The XML configuration file to be used by the Installation Wizard.
  51      If this option is not used then the installation script tries to
  52      define the Linux version and use the corresponding XML file if it
  53      is present. For examle, for the Linux Mandrake 10.1  the
  54      config_Mandrake_10.1.xml  file will be used by default. If the
  55      appropriate file is not found, the file config.xml will be
  56      used. This file refers to the basic target platform which is
  57      Linux Mandrake 10.1 for SALOME 3.0 and newer. If config.xml file
  58      is also not found, the warning message box is shown (in GUI mode)
  59      or printed to the console (in batch mode) and the Installation
  60      Wizard quits.
  61
  62      -d DIR / --target=DIR
  63
  64      The target directory SALOME platform to be installed to. If used,
  65      this option overrides the default target directory, given in the
  66      configuration XML file (usually ${HOME}/salome_<version>, see
  67      here for more detail).
  68
  69      -t DIR / --tmp=DIR
  70
  71      The directory, which is used for temporary files. If used, this
  72      option overrides the default temporary directory, given in the
  73      configuration xml file (usually /tmp, see here for more detail).
  74
  75      -a / --all-from-sources
  76
  77      Force all products to be installed from sources including SALOME
  78      modules.If this option is used all the default installation modes
  79      are ignored.
  80
  81      -h / --help
  82
  83      Prints help information about available options.
  84
  85      -v / --version
  86
  87      Prints version information (Note: this is the Installation
  88      Wizard's version number, not of SALOME platform).
  89
  90      For more detailed information about the Installation Wizard refer to the
  91      readme.html file in the doc directory.
  92
  93 ================================================================================
  94
  95   2. Running of SALOME
  96
  97      This section describes how to run SALOME platform after its installation
  98      with the Installation Wizard.
  99
 100      2.1. Setting of the environment for SALOME
 101
 102           Installation Wizard creates some environment files to simplify
 103           the procedure of launching of SALOME. These shell scripts set all
 104           necessary environment variables for all products you have installed.
 105           These files are:
 106                * env_products.csh + env_products.sh in the target directory;
 107                  these files can be used for the launching of SALOME.
 108                * salome.csh + salome.sh in the KERNEL module's sources/binaries
 109                  root directories; these files are the copies of the
 110                  corresponding env_products.* files.
 111                * env_build.csh + env_build.sh in the target directory;
 112                  these files contain minimal environment settings necessary
 113                  to build SALOME packages from sources (see paragraph 4).
 114
 115           To set SALOME environment just type in the terminal window:
 116
 117                cd <KERNEL_ROOT_DIR>
 118                source salome.sh
 119           or
 120                cd <KERNEL_ROOT_DIR>
 121                source salome.csh
 122
 123           where <KERNEL_ROOT_DIR> is KERNEL binaries directory, e.g.
 124           KERNEL_3.2.6 for the 3.2.6 version.
 125
 126      2.2. Launching of SALOME
 127
 128           After you set environment you can start SALOME. Go to the KERNEL
 129           module's binaries directory (KERNEL_3.2.6/bin/salome for the version
 130           3.2.6) by using of 'cd' command and then type:
 131
 132                runSalome [<parameters>]
 133
 134           This will start SALOME according to the launching parameters which
 135           are described in the configuration files: SalomeApp.xml in the
 136           <GUI_ROOT_DIR>/share/salome/resources/gui folder and
 137           .SalomeApprc.<version_number> file, located in your home
 138           directory (where <version_number> is SALOME version number).
 139           If the user configuration file does not exist, it is automatically
 140           created when exiting SALOME GUI.
 141
 142           You can modify SALOME launching options by editing your
 143           ~/.SalomeApprc.<version_number> file (not all the options are
 144           listed below):
 145
 146           <section name="launch">
 147             <parameter name="gui"        value="yes"/>
 148             <parameter name="splash"     value="yes"/>
 149             <parameter name="file"       value="no"/>
 150             <parameter name="key"        value="no"/>
 151             <parameter name="interp"     value="no"/>
 152             <parameter name="logger"     value="no"/>
 153             <parameter name="xterm"      value="no"/>
 154             <parameter name="portkill"   value="no"/>
 155             <parameter name="killall"    value="no"/>
 156             <parameter name="modules"    value="GEOM,SMESH,VISU,SUPERV,MED,COMPONENT"/>
 157             <parameter name="embedded"   value="SalomeAppEngine"/>
 158             <parameter name="standalone" value="study,pyContainer,cppContainer,registry,moduleCatalog"/>
 159           </section>
 160
 161           Some parameters described in configuration file can be overrided by
 162           using of corresponding command-line options for runSalome script:
 163
 164           --gui
 165                 Launch GUI desktop
 166           --logger
 167                 Use logger server
 168           --xterm
 169                 Start each server in its own xterm console window
 170           --portkill
 171                 Kill SALOME, running on the current port
 172           --killall
 173                 Kill SALOME, running on all ports
 174           --modules=<module>,<module>,...,<module>
 175                 Use module(s), possible values are GEOM,SMESH,VISU,MED,SUPERV,etc.
 176           --embedded=<server>,<server>,...<server>
 177                 Start specified server/container(s) embedded in SALOME Session server
 178                 (i.e. running in the same process), possible values are registry,
 179                 study, moduleCatalog, cppContainer, registry
 180           --standalone=<server>,<server>,...<server>
 181                 Start standalone server/container(s), possible values are registry,
 182                 study, registry, moduleCatalog, cppContainer, pyContainer, supervContainer.
 183
 184           Additional launch settings are given in other sections, which refer to certain
 185           modules. For example, SMESH plugins which should be used in the SALOME launch
 186           session can be mentioned in the <SMESH> section, e.g.:
 187
 188           <section name="SMESH">
 189             <parameter name="name"       value="Mesh"/>
 190             <parameter name="icon"       value="ModuleMesh.png"/>
 191             <parameter name="plugins"    value="StdMeshers,NETGENPlugin"/>
 192           </section>
 193
 194 ================================================================================
 195
 196   3. Installation notes
 197
 198      3.1. Time required for the installation
 199
 200           Installation of all products which are necessary to build and
 201           start SALOME is a time-consuming process and needs from the user to be
 202           patient.
 203           The quickest way to install SALOME is installation from the binaries.
 204           In this mode the Installation Wizard just extracts all precompiled
 205           products from the corresponding archives (except those products
 206           which can be installed only by compiling from sources).
 207           The installation from sources requires much more time than from
 208           binaries because in this case the Installation Wizard extracts and
 209           then builds each product using the product's own compilation
 210           procedure.
 211           The installation time also depends on the computer and platform used.
 212           For example, to install SALOME on Pentium IV-2GHz, Linux Mandrake 10.1,
 213           time of the installation is:
 214
 215                - from binaries: ~10 minutes;
 216                - from sources: more than 24 hours.
 217
 218      3.2. Log files
 219
 220           The Installation Wizard displays the installation progress in the
 221           corresponding windows (see readme.html). The Wizard uses a temporary
 222           directory to store and build the products. During the installation
 223           it produces some log files in this directory. If you suspect that
 224           program hangs you can check the log files. These files have names
 225           in capital letters like CONFIGURE.LOG, MAKE.LOG, MAKEINSTALL.LOG, etc.
 226
 227      3.3. Testing of installed SALOME platform
 228
 229           There is a python script which allows to test shortly all SALOME
 230           modules. This script can help to check if SALOME has been installed
 231           successfully.
 232           To test SALOME platform, run SALOME desktop (see section 2), then
 233           create a new study window (menu command 'File/New') and then type
 234           in the study's embedded python console window:
 235
 236                import salome_test
 237
 238           When running, the script loads different modules (Geometry, Mesh, Med,
 239           Post-Pro and Supervisor) and tests different functionality of these
 240           modules. You can watch script running progress in the embedded
 241           python console window.
 242
 243           Note: the salome_test.py scripts require SALOME samples
 244           module (SAMPLES_SRC) to be installed (this module includes set of sample
 245           MED, Python, Supervisor graph, etc files).
 246           Environment variable DATA_DIR should point to the SALOME
 247           samples module directory.
 248
 249 ================================================================================
 250
 251   4. How to build SALOME modules from sources
 252
 253      This section describes the way how to build SALOME modules manually from
 254      sources distribution provided with Installation Wizard.
 255
 256      4.1. General procedure
 257
 258           If you want to build SALOME modules from sources, install all prerequisite
 259           products, required for the platform and SALOME modules sources.
 260           Then follow the scenario described below.
 261           In this scenario it is supposed that you have installed SALOME
 262           modules sources in the /home/salome directory. The name of each module
 263           sources directory depends on the version of the platform, for example,
 264           KERNEL_SRC_3.2.6 for KERNEL module of SALOME version 3.2.6.
 265
 266           The order of compilation and installation should be performed according
 267           to the dependancies between modules:
 268
 269           Main SALOME modules:
 270
 271           * KERNEL -> no dependancies
 272           * GUI -> KERNEL
 273           * GEOM -> KERNEL, GUI
 274           * MED -> KERNEL, GUI
 275           * SMESH -> KERNEL, GUI, GEOM, MED
 276           * VISU -> KERNEL, GUI, MED
 277           * SUPERV -> KERNEL, GUI
 278
 279           SMESH plugins:
 280
 281           * NETGENPLUGIN -> KERNEL, GUI, SMESH
 282           * GHS3DPLUGIN -> KERNEL, GUI, SMESH
 283
 284           Sample modules:
 285
 286           * COMPONENT -> KERNEL, MED
 287           * PYCALCULATOR -> KERNEL, MED
 288           * CALCULATOR -> KERNEL, MED
 289           * HELLO -> KERNEL, GUI
 290           * PYHELLO -> KERNEL
 291           * LIGHT -> KERNEL, GUI
 292
 293           Note: SMESH plugins and sample modules are optional. You may skip
 294           compiling them if you do not plan to use NETGEN and/or GHS3D meshing
 295           algorithms and do not want to build samples.
 296
 297           In general, each module (except KERNEL and GUI, of course) is optional for
 298           SALOME. If you do not need any module, just do not compile or install
 299           it. But remember that some modules require other ones to be built first
 300           (see dependancies table above).
 301
 302           To build KERNEL module:
 303
 304           - go to installation root directory (/home/salome in this example):
 305
 306                cd /home/salome
 307
 308           - to set environment variables use bash or csh script, depending on
 309             your shell:
 310
 311                source ../env_products.csh
 312             or
 313                source ../env_products.sh
 314
 315           - create build directory for the KERNEL module:
 316
 317                mkdir KERNEL_build
 318                cd KERNEL_build
 319
 320           - create a configuration script by typing
 321
 322                ../KERNEL_SRC_3.2.6/build_configure
 323
 324           - run configure script which will check the environment and create
 325             Makefile files:
 326
 327                ../KERNEL_SRC_3.2.6/configure --prefix=/home/salome/KERNEL_install
 328
 329           Note, that --prefix option defines the directory where you want to
 330           install KERNEL module after 'make install' procedure. configure script
 331           accepts also a lot of other parameters (for example, to build the module
 332           in the optimized mode use --disable-debug --enable-production keys).
 333           More about certain module's configure options you can learn by using
 334           --help (-h) parameter.
 335
 336           - build and (optionally) install KERNEL module:
 337
 338                make
 339                make install
 340
 341           After you have completed this scenario, KERNEL module is built and
 342           installed into /home/salome/KERNEL_install directory.
 343
 344           - modify your environment scripts:
 345
 346           * for bash:
 347
 348                export KERNEL_ROOT_DIR=/home/salome/KERNEL_install
 349             or
 350                export KERNEL_ROOT_DIR=/home/salome/KERNEL_build
 351                (if make install step was not performed).
 352
 353           * for csh:
 354
 355                setenv KERNEL_ROOT_DIR /home/salome/KERNEL_install
 356             or
 357                setenv KERNEL_ROOT_DIR /home/salome/KERNEL_build
 358                (if make install step was not performed).
 359
 360           - then repeat this scenario for other modules you want to build taking
 361             into account the dependancies between modules (see dependancies table
 362             above).
 363
 364           Note: if the compilation fails it may be caused by bad environment.
 365           In this case you should check that environment script you use
 366           (salome.csh or salome.sh) contains the following lines for each module MODULE:
 367
 368           * for bash:
 369
 370                export MODULE_ROOT_DIR=/home/salome/<MODULE_distribution>
 371
 372           * for csh:
 373
 374                setenv MODULE_ROOT_DIR /home/salome/<MODULE_distribution>
 375
 376           where <MODULE_distribution> is a MODULE_build or MODULE_install (see above).
 377
 378      4.2. Automatic build procedure: build.csh and build.sh scripts
 379
 380           SALOME Installation Wizard includes two scripts which can be used
 381           for automatic building of SALOME modules from sources packages:
 382           build.csh and build.sh. The scripts are installed into the top-level
 383           installation directory (the same directory where env_products.[c]sh
 384           files are generated).
 385
 386           The build.csh and buils.sh scripts implement the same functionality
 387           and support the same set of options, but for different shells.
 388           Use build.csh script for csh and build.sh for bash.
 389           The description below refers to both scripts.
 390
 391           To use the script just install SALOME sources packages with the
 392           Installation Wizard, then cd to the SALOME installation directory
 393           and type:
 394
 395                ./build.csh
 396
 397           By default, build.csh only compiles the modules but does not install them,
 398           i.e. does not perform 'make install' step.
 399           To do this, use -i option or -p <prefix> where <prefix> is the
 400           directory SALOME modules should be installed to.
 401
 402           If you want to build only some SALOME modules, just pass them as
 403           parameters, e.g.:
 404
 405                ./build.csh -i KERNEL MED GEOM
 406
 407           The script also provides some other options which specify compiling
 408           and installation parameters. You can learn about options by using
 409           -h key:
 410
 411                ./build.csh -h
 412
 413           When you run build.csh at first time it is not necessary to pass
 414           -b, -c parameters. The script detects if build procedure has not yet
 415           been performed and runs build_configure, configure scripts
 416           in this case automatically.
 417
 418           Note: for avoiding of collisions it is recommended not to install
 419           SALOME binaries packages with Installation Wizard if you plan to build
 420           SALOME modules from sources packages or to edit/comment all rows
 421           in env_products.csh file concerning binaries packages.
 422
 423           Note: use -d option carefully because in this case the script removes
 424           existing (previously installed) SALOME modules.
 425
 426           Note: please, take into account 'make install' step is
 427           obligatory for the KERNEL module. Build directory of KERNEL
 428           can not be pointed as KERNEL_ROOT_DIR. This is an exception
 429           for the SALOME modules. So you should use one of options -i
 430           or -p of build.sch script when building KERNEL module.
 431
 432           Note: build.(c)sh scripts do not modify the environment files
 433           (env_products.csh, etc). You should do it by yourself.
 434
 435 ================================================================================