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 3.1.0*
  10 *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 ===================     ===================================================
 113 CAS-5.2.4               OpenCascade (try binaries,a source patch is needed)
 114 VTK-4.2.6               VTK 3D-viewer
 115 PyQt-3.13               Python-Qt Wrapper
 116 Python-2.3.5            Python interpreter
 117 SWIG-1.3.24             SWIG library
 118 boost-1_32_0            C++ library (only include templates are used)
 119 hdf5-1.6.2              Files Database library
 120 med-2.2.2               MED Data Format support for file records
 121 omniORB-4.0.5           ORB used in SALOME
 122 qt-x11-free-3.3.3       Qt library
 123 qwt-4.2                 Graph components for Qt
 124 sip4-4.1.1              langage binding software
 125 ===================     ===================================================
 126
 127 And, in order to build the documentation:
 128
 129 ===================     ===================================================
 130 doxygen-1.4.2
 131 graphviz-2.2.1
 132 ===================     ===================================================
 133
 134
 135 Additionnal software may be installed for optional features:
 136
 137 ===================     ===================================================
 138 netgen4.3 + patch
 139 tix8.1.4
 140 openpbs-2.3.16
 141 lsf-???
 142 ===================     ===================================================
 143
 144
 145
 146 3.1 To Do
 147 ~~~~~~~~~
 148 - Instructions for installing these software programs can be found in a
 149   special note doc/configuration_examples/install-prerequis.
 150 - Installation shell scripts are also provided.
 151   These scripts have to be adapted to your own configuration.
 152
 153 - See doc/configuration_examples/*
 154
 155 In the following, we assume that all the third-party softwares are
 156 installed in the same root directory, named <salomeroot>/prerequis.
 157 Then, your file system should probably look like::
 158
 159   <salomeroot>/prerequis/Python-2.2.2
 160   <salomeroot>/prerequis/omniORB-3.0.5
 161   <salomeroot>/prerequis/qt-x11-free-3.0.5
 162   ...
 163
 164
 165 4. Preparing the shell environment
 166 ----------------------------------
 167
 168 Some variables have to be set to get acces to third-party software
 169 components (include files, executable, library, ...) during building
 170 process and runtime.
 171
 172 The shell file prerequis.sh, embedded in the KERNEL source package,
 173 provides a template for setting those variables. In this example, all the
 174 softwares are supposed to be installed in the same root directory,
 175 named here INSTALLROOT.
 176
 177 Copy the prerequis.sh in a working directory and adjust the settings
 178 to your own configuration. To get the shell prepared, just
 179 execute the following command in the building shell:
 180
 181 $ source prerequis.sh
 182
 183 (we assume here a ksh or bash mode)
 184
 185
 186 5. Installing the KERNEL component
 187 ----------------------------------
 188
 189 We use here the notation <kernel_src> to specify the source directory
 190 of the KERNEL component. The shell environment is supposed to have
 191 been set (cf. 4).
 192
 193 Installing the KERNEL from a source package needs three directories:
 194
 195 - the source directory, denoted here by <kernel_src>.
 196
 197 - the build directory, denoted by <kernel_build> in the following. This
 198   directory can't be the same directory as <kernel_src>.
 199
 200 - the install directory, denoted by <kernel_install> in the following. This
 201   directory can't be the same directory as <kernel_src> or
 202   <kernel_build>.
 203
 204 The installing process is:
 205
 206 STEP 1:
 207   preparing directories
 208
 209   create the <kernel_build> and the <kernel_install> directories::
 210
 211     $ mkdir <kernel_build>
 212     $ mkdir <kernel_install>
 213
 214 STEP 2:
 215   build configure script
 216
 217   go to <kernel_src> directory and generate the "configure" script::
 218
 219     $ cd <kernel_src>
 220     $ ./build_configure
 221
 222   If it doesn't work, check your system automake tools as specified in
 223   section [2].
 224
 225 STEP 3:
 226   configure the building process
 227   go to the build directory and execute the configuration process::
 228
 229     $ cd <kernel_build>
 230     $ <kernel_src>/configure --prefix=<kernel_install>
 231
 232   Note that <kernel_install> must be an absolute path.
 233
 234   When the configure process is complete, check the status of
 235   third-party softwares detection. You should have a status like::
 236
 237     ---------------------------------------------
 238     Summary
 239     ---------------------------------------------
 240     Configure
 241            cc : yes
 242         boost : yes
 243      lex_yacc : yes
 244        python : yes
 245          swig : yes
 246       threads : yes
 247        OpenGL : yes
 248            qt : yes
 249           vtk : yes
 250          hdf5 : yes
 251          med2 : yes
 252       omniORB : yes
 253           occ : yes
 254           sip : yes
 255          pyqt : yes
 256           qwt : yes
 257       doxygen : yes
 258      graphviz : no
 259       openpbs : no
 260           lsf : no
 261     Default ORB   : omniORB
 262     ----------------------------------------------
 263
 264 If a software get a status "no", then it's not "seen" in the system:
 265
 266 - the software is not installed, or
 267 - the shell environment is not set correctly.
 268
 269 In this example, the software programs graphviz, openpbs and lsf are not
 270 installed (optional for most usages).
 271
 272
 273 STEP 4 :
 274   Building the binary files
 275
 276   Execute make in the <kernel_build> directory::
 277
 278     $ make
 279
 280
 281 STEP 5:
 282   Installing binary files, scripts and documentation
 283
 284   Execute install target in the <kernel_build> directory::
 285
 286     $ make install
 287
 288
 289 6. Installing the SALOME components
 290 -----------------------------------
 291
 292 TInstalling a component <COMPONENT> is done by following the same
 293 instructions as given for the KERNEL, replacing KERNEL by
 294 <COMPONENT> (build_configure, configure, make, make install).
 295
 296 You just have to be aware of the dependencies between components:
 297
 298 - MED    depends on KERNEL
 299 - GEOM   depends on KERNEL
 300 - SMESH  depends on KERNEL, MED, GEOM
 301 - VISU   depends on KERNEL, MED
 302 - SUPERV depends on KERNEL
 303
 304 For example, installing the component SMESH needs the previous
 305 installation of the KERNEL component, and then the GEOM and MED components.
 306
 307 The building process uses the variables <COMPONENT>_ROOT_DIR to
 308 localize the dependant components. The variables must be set to the
 309 install path directory of the components <COMPONENT> (ex:
 310 KERNEL_ROOT_DIR=<kernel_install>).
 311
 312 In the above example, the three variables KERNEL_ROOT_DIR,
 313 GEOM_ROOT_DIR and MED_ROOT_DIR have to be set before configuring the
 314 building process of the SMESH component (STEP 3).
 315
 316
 317 7. Runtime
 318 ----------
 319
 320 See SALOME_Application_ to define your own configuration of SALOME and run it
 321 on one or several computers. This is the recommended way of configuration.
 322
 323 .. _SALOME_Application: ./SALOME_Application.html
 324
 325 The following explains the general principles.
 326
 327 To run the SALOME platform, the procedure is:
 328
 329 - set the shell environment to get acces to third-party softwares::
 330
 331    $ source prerequis.sh
 332
 333 - define the SALOME configuration by setting the whole set of
 334   variables <COMPONENT>_ROOT_DIR. Here, you just have to set the
 335   kernel and the components you need::
 336
 337     $ export KERNEL_ROOT_DIR=<kernel_install>
 338     $ export MED_ROOT_DIR=<med_install>
 339     $ ...
 340
 341 - define the CORBA configuration file by setting the variable
 342   OMNIORB_CONFIG. This variable must be set to a writable file
 343   path. The file may be arbitrary chosen and doesn't need to exist
 344   before running. We suggest::
 345
 346     $ export OMNIORB_CONFIG=$HOME/.omniORB.cfg
 347
 348 - run the SALOME platform by executing the script runSalome::
 349
 350     $KERNEL_ROOT_DIR/bin/salome/runSalome
 351
 352
 353 8. Suggestions and advices
 354 --------------------------
 355
 356 For convenience or customization, we suggest the following organisation:
 357
 358 - chose and create a root directory for the SALOME platform, say
 359   <salomeroot>.
 360
 361 - install the third-party softwares in a sub-directory "prerequis"
 362
 363 - install the SALOME components in a sub-directory "SALOME2"
 364
 365 - make personnal copies of the files prerequis.sh and runSalome in
 366   <salomeroot>::
 367
 368     $ cp <kernel_src>/prerequis.sh <rundir>/.
 369     $ cp <kernel_install>/bin/salome/runSalome <rundir>/.
 370
 371   Edit the file prerequis.sh and adjust it to your own configuration.
 372
 373 - define the SALOME2 configuration
 374
 375   This step consists in setting the KERNEL_ROOT_DIR, the whole set of
 376   variables <COMPONENT>_ROOT_DIR you need, and the OMNIORB_CONFIG
 377   variable.
 378
 379   We suggest to create a shell file envSalome.sh containing those
 380   settings. Then the configuration consists in loading envSalome.sh in
 381   the runtime shell::
 382
 383     $ source envSalome.sh
 384
 385 - When installed with this file organisation, running SALOME is done
 386   with the following shell commands::
 387
 388     $ source <salomeroot>/prerequis.sh
 389     $ source <salomeroot>/envSalome.sh
 390     $ ./runSalome
 391
 392
 393 -------------------------------------------------------------------------------
 394
 395 +----------------------------------+------------------------------------------+
 396 | `General KERNEL documentation`_  | `End User KERNEL Doxygen documentation`_ |
 397 +----------------------------------+------------------------------------------+
 398
 399 .. _`General KERNEL documentation`:           ./index.html
 400 .. _`End User KERNEL Doxygen documentation`:  ./tui/KERNEL/index.html