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