INSTALL

   1 # Copyright (C) 2007-2015  CEA/DEN, EDF R&D, OPEN CASCADE
   2 #
   3 # Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
   4 # CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
   5 #
   6 # This library is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU Lesser General Public
   8 # License as published by the Free Software Foundation; either
   9 # version 2.1 of the License, or (at your option) any later version.
  10 #
  11 # This library is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # Lesser General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU Lesser General Public
  17 # License along with this library; if not, write to the Free Software
  18 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19 #
  20 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21 #
  22
  23
  24 -------------------------------- Quick install --------------------------------
  25
  26
  27 This library is based on CMake build system (http://www.cmake.org/), which
  28 means that you must have CMake installed on your system (minimum version 2.4)
  29 in order to build and install libBatch.
  30
  31 You can then go to the directory where you extracted libBatch package and type:
  32
  33 $ cmake
  34 $ make
  35 $ make install
  36
  37 That's all!
  38
  39
  40 --------------------- Detailed installation instructions ----------------------
  41
  42
  43 1. Prerequisites
  44
  45
  46 First of all, you have to check (or install if needed) the dependant software
  47 programs on your system. These programs are:
  48
  49 - CMake build system version 2.4 or newer (http://www.cmake.org/)
  50 - C++ compiler with standard libraries
  51 - pthread library
  52
  53 Other products are optional and used to build libBatch interfaces to various
  54 batch systems and to generate wrappings and documentation:
  55
  56 - LSF headers and libraries (to build the interface to LSF batch system)
  57 - OpenPBS headers and libraries (to build the interface to OpenPBS)
  58 - Several Unix remote control commands like ssh and scp (for local submission)
  59 - Python and SWIG (to build Python wrappings)
  60 - makeinfo (to generate the documentation)
  61
  62
  63 2. Building and installing the library
  64
  65
  66 To build the library, you will have to extract the source package in a
  67 directory where you have write permissions (probably done since you're reading
  68 this file). You can then build the library directly in the source tree, but it
  69 is strongly advised to use an independant build tree. For that, just go to the
  70 directory where you extracted libBatch and type for instance:
  71
  72 $ mkdir ../libBatch-build
  73 $ cd ../libBatch-build
  74
  75 After that, you will just need to run cmake to generate the Makefiles and to
  76 run make and make install:
  77
  78 $ cmake ../libBatch-X.X.X                             (X's are version numbers)
  79 $ make
  80 $ make install
  81
  82 Note that CMake will look for the prerequisites and optional products in the
  83 standard directories and environment variables. To change this behavior, you
  84 can either preset the environment variables CMAKE_INCLUDE_PATH and
  85 CMAKE_LIBRARY_PATH (see CMake documentation for more details) or use CMake
  86 graphical interface. For this, run cmake one time to populate the cache and
  87 then run ccmake:
  88
  89 $ cmake ../libBatch-X.X.X                             (X's are version numbers)
  90 $ ccmake ../libBatch-X.X.X                            (X's are version numbers)
  91
  92 You will then be able to change several variables to control the way libBatch
  93 is built (i.e. install path, products path, components to install, ...). Then
  94 run make and make install like before to build and install the library.
  95
  96 Also note that you won't be able to install libBatch in the default directory
  97 if you don't have administrators rights on your machine (and anyway, it's not
  98 advised to install anything manually in the /usr directory). To specify the
  99 installation directory, you can either use the graphical interface or directly
 100 type on cmake command line:
 101
 102 $ cmake ../libBatch-X.X.X -DCMAKE_INSTALL_PREFIX=<installdir>
 103
 104
 105 3. Testing
 106
 107
 108 The build system creates a test target that can be used to automatically test
 109 some features of the library. The test coverage for this library is currently
 110 quite poor. Remember that since the tests use connections to remote batch
 111 systems, the first causes of failure are network and authentication errors. To
 112 run the tests, you will first have to enable them by setting CMake variable
 113 LIBBATCH_BUILD_TESTS to ON. Then copy the file src/Core/Test/batchtest.conf to your
 114 home directory for instance. Edit this file according to your local
 115 configuration. Set the environment variable BATCH_TEST_CONFIG_FILE to the path
 116 to your own configuration file. To execute the autotests, just go to your build
 117 directory and type:
 118
 119 $ make test
 120
 121 The tests will be run successively and a summary will show you how many of them
 122 passed without error. Note that several tests need passwordless SSH
 123 authentication to succeed. You can configure this authentication with ssh-agent
 124 for instance. If one or several tests failed, you can find more detailed
 125 results in the file <build-dir>/Testing/Temporary/LastTest.log
 126
 127
 128 4. Building source and binary packages (for developers)
 129
 130
 131 You can directly build source or binary tgz packages for libBatch with CPack
 132 (included with CMake) packaging process. For this, just go to your build
 133 directory and type:
 134
 135 $ cmake ../libBatch-X.X.X                             (X's are version numbers)
 136 $ make package                                             (for binary package)
 137 $ make package_source                                      (for source package)
 138
 139
 140 5. Note for the users of Microsoft Windows operating system
 141
 142
 143 The support for this library on Windows operating system is still partial and
 144 experimental. Some features are not and will not be implemented for this
 145 system. Nevertheless it is possible to compile the library and launch some
 146 batch jobs from a computer running Windows. This section only gives some
 147 guidelines, without any warranty, to install libBatch on Windows.
 148
 149 First you will need to install a library providing pthread implementation. For
 150 this we tested Pthreads-win32 (http://sourceware.org/pthreads-win32/) but other
 151 implementations may exist.
 152
 153 You will also need a compiler for Win32 platform. We tested MinGW with MSYS
 154 environment (http://www.mingw.org/), and Microsoft Visual C++ 2005 Express.
 155 Other compilers might also work but it is not guaranteed.
 156
 157 Then you will have to install and run CMake, and you should be able to compile
 158 libBatch and run some basic examples.
 159
 160 If you need to use SSH protocol to submit jobs to your cluster, you will need
 161 a SSH implementation for Windows operating system. PuTTY is a good choice for
 162 that (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). Once
 163 installed, add the path to your PuTTY installation in the PATH environment
 164 variable and run CMake. The build system will detect it and the libBatch will
 165 use it for SSH-based transfers with the server.