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