doc/salome/install.dox

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