doc/INSTALL.txt

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