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