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