doc/INSTALL.txt

   1
   2 =================================================================
   3 Installation instructions, up to date for 3.0 version
   4 =================================================================
   5
   6 You'll find here generic instructions for installing the SALOME2 platform.
   7
   8 +-------------------------------------------+
   9 | **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
  10 +-------------------------------------------+
  11
  12 Summary
  13 -------
  14
  15 `1. Quick Overview`_
  16
  17 `2. System configuration`_
  18
  19 `3. Third-party dependencies`_
  20
  21 `4. Preparing the shell environment`_
  22
  23 `5. Installing the KERNEL component`_
  24
  25 `6. Installing the SALOME components`_
  26
  27 `7. Runtime`_
  28
  29 `8. Suggestions and advices`_
  30
  31
  32 1. Quick Overview
  33 -----------------
  34
  35 First of all, you have to check (or install if needed) the dependant
  36 software programs on your system. These programs are:
  37
  38 - common development tools as gcc, automake, autoconf and libtools.
  39 - third party softwares used in SALOME building or runtime process
  40   (python, OCC, VTK, ...)
  41
  42 Further details can be found in sections [2] and [3].
  43
  44 If the dependencies are installed on your system, then you have to set
  45 your shell environment to get access to the software components
  46 (cf. [4]. "Preparing the shell environment").
  47
  48 The next step is to install the KERNEL (cf. [5] "Installing KERNEL"):
  49
  50 ::
  51
  52 $ mkdir <kernel_build>
  53 $ mkdir <kernel_install>
  54 $ cd <kernel_src>
  55 $ ./build_configure
  56 $ cd <kernel_build>
  57 $ <kernel_src>/configure --prefix=<kernel_install>
  58 $ make
  59 $ make install
  60
  61 Then, the SALOME components GEOM, MED, VISU, ... can be installed
  62 with a similar procedure (cf. [6]).
  63
  64 Eventually, the platform can be run by executing the shell script
  65 runSalome (cf. [7]). Here, somme additionnal variables have to be set
  66 to describe the SALOME runtime configuration (<COMPONENT>_ROOT_DIR,
  67 OMNIORB_CONFIG)
  68
  69 The following provides you with specific instructions for each step.
  70
  71
  72 2. System configuration
  73 -----------------------
  74
  75 SALOME is compiled and tested on differents platforms with native packages:
  76 - Debian sarge
  77 - Mandrake 10.1
  78 - ...
  79
  80 If you have another platform, we suggest the following configuration
  81 for building process:
  82
  83 - gcc-3.3.x or 3.4.x
  84 - automake-1.7 or more (only aclocal is used)
  85 - autoconf-2.59
  86 - libtool-1.5.6
  87
  88 remarks:
  89
  90 - This is the minimum level of automake, autoconf and libtool, if you need
  91   to compile all the third party softwares (included OpenCascade 5.2.x).
  92
  93 3. Third-party dependencies
  94 ---------------------------
  95
  96 The SALOME platform relies on a set of third-party softwares. The
  97 current version depends on the following list
  98 (versions given here are from Debian Sarge, except OpenCascade, VTK and MED,
  99 which are not Debian packages):
 100
 101 ===================     ===================================================
 102 CAS-5.2.4               OpenCascade (try binaries,a source patch is needed)
 103 VTK-4.2.6               VTK 3D-viewer
 104 PyQt-3.13               Python-Qt Wrapper
 105 Python-2.3.5            Python interpreter
 106 SWIG-1.3.24             SWIG library
 107 boost-1_32_0            C++ library (only include templates are used)
 108 hdf5-1.6.2              Files Database library
 109 med-2.2.2               MED Data Format support for file records
 110 omniORB-4.0.5           ORB used in SALOME
 111 qt-x11-free-3.3.3       Qt library
 112 qwt-4.2                 Graph components for Qt
 113 sip4-4.1.1              langage binding software
 114 ===================     ===================================================
 115
 116 And, in order to build the documentation:
 117
 118 ===================     ===================================================
 119 doxygen-1.4.2
 120 graphviz-2.2.1
 121 ===================     ===================================================
 122
 123
 124 Additionnal software may be installed for optional features:
 125
 126 ===================     ===================================================
 127 netgen4.3 + patch
 128 tix8.1.4
 129 openpbs-2.3.16
 130 lsf-???
 131 ===================     ===================================================
 132
 133
 134
 135 3.1 To Do
 136 ~~~~~~~~~
 137 - Instructions for installing these software programs can be found in a
 138   special note doc/configuration_examples/install-prerequis.
 139 - Installation shell scripts are also provided.
 140   These scripts have to be adapted to your own configuration.
 141
 142 - See doc/configuration_examples/*
 143
 144 In the following, we assume that all the third-party softwares are
 145 installed in the same root directory, named <salomeroot>/prerequis.
 146 Then, your file system should probably look like::
 147
 148   <salomeroot>/prerequis/Python-2.2.2
 149   <salomeroot>/prerequis/omniORB-3.0.5
 150   <salomeroot>/prerequis/qt-x11-free-3.0.5
 151   ...
 152
 153
 154 4. Preparing the shell environment
 155 ----------------------------------
 156
 157 Some variables have to be set to get acces to third-party software
 158 components (include files, executable, library, ...) during building
 159 process and runtime.
 160
 161 The shell file prerequis.sh, embedded in the KERNEL source package,
 162 provides a template for setting those variables. In this example, all the
 163 softwares are supposed to be installed in the same root directory,
 164 named here INSTALLROOT.
 165
 166 Copy the prerequis.sh in a working directory and adjust the settings
 167 to your own configuration. To get the shell prepared, just
 168 execute the following command in the building shell:
 169
 170 $ source prerequis.sh
 171
 172 (we assume here a ksh or bash mode)
 173
 174
 175 5. Installing the KERNEL component
 176 ----------------------------------
 177
 178 We use here the notation <kernel_src> to specify the source directory
 179 of the KERNEL component. The shell environment is supposed to have
 180 been set (cf. 4).
 181
 182 Installing the KERNEL from a source package needs three directories:
 183
 184 - the source directory, denoted here by <kernel_src>.
 185
 186 - the build directory, denoted by <kernel_build> in the following. This
 187   directory can't be the same directory as <kernel_src>.
 188
 189 - the install directory, denoted by <kernel_install> in the following. This
 190   directory can't be the same directory as <kernel_src> or
 191   <kernel_build>.
 192
 193 The installing process is:
 194
 195 STEP 1:
 196   preparing directories
 197
 198   create the <kernel_build> and the <kernel_install> directories::
 199
 200     $ mkdir <kernel_build>
 201     $ mkdir <kernel_install>
 202
 203 STEP 2:
 204   build configure script
 205
 206   go to <kernel_src> directory and generate the "configure" script::
 207
 208     $ cd <kernel_src>
 209     $ ./build_configure
 210
 211   If it doesn't work, check your system automake tools as specified in
 212   section [2].
 213
 214 STEP 3:
 215   configure the building process
 216   go to the build directory and execute the configuration process::
 217
 218     $ cd <kernel_build>
 219     $ <kernel_src>/configure --prefix=<kernel_install>
 220
 221   Note that <kernel_install> must be an absolute path.
 222
 223   When the configure process is complete, check the status of
 224   third-party softwares detection. You should have a status like::
 225
 226     ---------------------------------------------
 227     Summary
 228     ---------------------------------------------
 229     Configure
 230            cc : yes
 231         boost : yes
 232      lex_yacc : yes
 233        python : yes
 234          swig : yes
 235       threads : yes
 236        OpenGL : yes
 237            qt : yes
 238           vtk : yes
 239          hdf5 : yes
 240          med2 : yes
 241       omniORB : yes
 242           occ : yes
 243           sip : yes
 244          pyqt : yes
 245           qwt : yes
 246       doxygen : yes
 247      graphviz : no
 248       openpbs : no
 249           lsf : no
 250     Default ORB   : omniORB
 251     ----------------------------------------------
 252
 253 If a software get a status "no", then it's not "seen" in the system:
 254
 255 - the software is not installed, or
 256 - the shell environment is not set correctly.
 257
 258 In this example, the software programs graphviz, openpbs and lsf are not
 259 installed (optional for most usages).
 260
 261
 262 STEP 4 :
 263   Building the binary files
 264
 265   Execute make in the <kernel_build> directory::
 266
 267     $ make
 268
 269
 270 STEP 5:
 271   Installing binary files, scripts and documentation
 272
 273   Execute install target in the <kernel_build> directory::
 274
 275     $ make install
 276
 277
 278 6. Installing the SALOME components
 279 -----------------------------------
 280
 281 TInstalling a component <COMPONENT> is done by following the same
 282 instructions as given for the KERNEL, replacing KERNEL by
 283 <COMPONENT> (build_configure, configure, make, make install).
 284
 285 You just have to be aware of the dependencies between components:
 286
 287 - MED    depends on KERNEL
 288 - GEOM   depends on KERNEL
 289 - SMESH  depends on KERNEL, MED, GEOM
 290 - VISU   depends on KERNEL, MED
 291 - SUPERV depends on KERNEL
 292
 293 For example, installing the component SMESH needs the previous
 294 installation of the KERNEL component, and then the GEOM and MED components.
 295
 296 The building process uses the variables <COMPONENT>_ROOT_DIR to
 297 localize the dependant components. The variables must be set to the
 298 install path directory of the components <COMPONENT> (ex:
 299 KERNEL_ROOT_DIR=<kernel_install>).
 300
 301 In the above example, the three variables KERNEL_ROOT_DIR,
 302 GEOM_ROOT_DIR and MED_ROOT_DIR have to be set before configuring the
 303 building process of the SMESH component (STEP 3).
 304
 305
 306 7. Runtime
 307 ----------
 308
 309 See SALOME_Application_ to define your own configuration of SALOME and run it
 310 on one or several computers. This is the recommended way of configuration.
 311
 312 .. _SALOME_Application: ./SALOME_Application.html
 313
 314 The following explains the general principles.
 315
 316 To run the SALOME platform, the procedure is:
 317
 318 - set the shell environment to get acces to third-party softwares::
 319
 320    $ source prerequis.sh
 321
 322 - define the SALOME configuration by setting the whole set of
 323   variables <COMPONENT>_ROOT_DIR. Here, you just have to set the
 324   kernel and the components you need::
 325
 326     $ export KERNEL_ROOT_DIR=<kernel_install>
 327     $ export MED_ROOT_DIR=<med_install>
 328     $ ...
 329
 330 - define the CORBA configuration file by setting the variable
 331   OMNIORB_CONFIG. This variable must be set to a writable file
 332   path. The file may be arbitrary chosen and doesn't need to exist
 333   before running. We suggest::
 334
 335     $ export OMNIORB_CONFIG=$HOME/.omniORB.cfg
 336
 337 - run the SALOME platform by executing the script runSalome::
 338
 339     $KERNEL_ROOT_DIR/bin/salome/runSalome
 340
 341
 342 8. Suggestions and advices
 343 --------------------------
 344
 345 For convenience or customization, we suggest the following organisation:
 346
 347 - chose and create a root directory for the SALOME platform, say
 348   <salomeroot>.
 349
 350 - install the third-party softwares in a sub-directory "prerequis"
 351
 352 - install the SALOME components in a sub-directory "SALOME2"
 353
 354 - make personnal copies of the files prerequis.sh and runSalome in
 355   <salomeroot>::
 356
 357     $ cp <kernel_src>/prerequis.sh <rundir>/.
 358     $ cp <kernel_install>/bin/salome/runSalome <rundir>/.
 359
 360   Edit the file prerequis.sh and adjust it to your own configuration.
 361
 362 - define the SALOME2 configuration
 363
 364   This step consists in setting the KERNEL_ROOT_DIR, the whole set of
 365   variables <COMPONENT>_ROOT_DIR you need, and the OMNIORB_CONFIG
 366   variable.
 367
 368   We suggest to create a shell file envSalome.sh containing those
 369   settings. Then the configuration consists in loading envSalome.sh in
 370   the runtime shell::
 371
 372     $ source envSalome.sh
 373
 374 - When installed with this file organisation, running SALOME is done
 375   with the following shell commands::
 376
 377     $ source <salomeroot>/prerequis.sh
 378     $ source <salomeroot>/envSalome.sh
 379     $ ./runSalome
 380