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