ThirdParty/README.ThirdParty

   1 A new design for the ThirdParty packages compilation and installation process:
   2 ==============================================================================
   3
   4 The main purpose of this new development is to build a complete ThirParty
   5 packages set for foam-extend-3.1 using only the original package source
   6 tarball and some patch files (when necessary).
   7
   8 A useful by-product of this development is also to provide some kind of
   9 binary packaging of the ThirdParty packages. There are currently two types of
  10 binary packaging generated by this compilation process: RPMs and compressed
  11 tarballs (TGZs)
  12
  13 The RPM package manager was selected to develop a first prototype. RPM is
  14 available for multiple flavors of Unix/Linux, and offers all the necessary
  15 functionnality to configured, patch, compile and install source code packages.
  16
  17 One of the main requirement for this new development is that the whole process
  18 needs to run and install in user-space, without the need to be root for
  19 installing the packages.
  20
  21 Here is what's available:
  22
  23  a: A set of RPM spec files for specific ThirdParty packages.
  24  b: A set of bash scripts to automate the complete sequence of downloading,
  25     compiling, installing and generating RPMs.
  26  c: An directory structure pre-configured and ready to proceed with the
  27     download, compilation and installation of chosen ThirdParty packages for
  28     OF-1.6-ext.
  29
  30
  31 1: Quick description of the main scripts:
  32 -----------------------------------------
  33    a: AllMake:
  34       Main wrapper script that will call AllMake.stage0 to AllMake.stage4
  35       scripts in sequence.
  36
  37    b: AllMake.stage0:
  38       This script is useful only for populating what I am calling the local "RPM
  39       vault" with pre-generated RPMs.
  40
  41       This is the script written to address the following use case:
  42       "I have some pre-generated RPM files, now what"
  43
  44       Basically, you call this script with a list of RPMs already generated by
  45       whichever of the AllMake.stage(1-4) in order to populate the local RPMS
  46       vault. Once in place in the RPM vault, these are the RPMs that will get
  47       directly installed by the AllMake.stage(1-4) scripts, instead of being
  48       regenerated by the normal compilation and install process of the
  49       ThirdParty packages.
  50
  51    c: AllMake.stage1:
  52       This script is taking care of the basic ThirdParty tools like compilers,
  53       flex, bison, cmake , python, etc.
  54       This compilation stage will generate .sh and .csh files that will be
  55       sourced by your file settings.sh or settings.csh in order to initialize
  56       the PATH and LD_LIBRARY_PATH environment variable for the stage1 packages.
  57
  58    d: AllMake.stage2:
  59       This script is taking care of the MPI communication libraries. Right now,
  60       only OpenMPI is supported.
  61       This compilation stage will generate .sh and .csh files that will be
  62       sourced by your file settings.sh or settings.csh in order to initialize
  63       the PATH and LD_LIBRARY_PATH environment variable for the stage2 packages.
  64
  65    e: AllMake.stage3:
  66       This script is taking care of the "standard" ThirdParty libraries like
  67       metis, scotch, mesquite, etc.
  68       This compilation stage will generate .sh and .csh files that will be
  69       sourced by your file settings.sh or settings.csh in order to initialize
  70       the PATH and LD_LIBRARY_PATH environment variable for the stage3 packages.
  71
  72    f: AllMake.stage4:
  73       This script is taking care of Paraview and QT (and this step will take an
  74       awfull long time to compile, honest...).
  75       This compilation stage will generate .sh and .csh files that will be
  76       sourced by your file settings.sh or settings.csh in order to initialize
  77       the PATH and LD_LIBRARY_PATH environment variable for the stage4 packages.
  78
  79    g: tools/makeThirdPartyFunctionsForRPM:
  80       A set of bash functions useful for wrapping the rpmbuild and rpm commands
  81
  82
  83 2: Important notice:
  84 --------------------
  85 Every single ThirdParty package will be installed with a set of companion .sh
  86 and .csh files one needs to source in order to properly initialize the PATH and
  87 LD_LIBRARY_PATH environment variables for running the packages.
  88
  89 Some packages will also create environments variables necessary for the
  90 compilation of some foam-extend libraries.
  91
  92 The scripts AllMake.stage[1-4] are taking care of refreshing the environment
  93 variable after the installation of every single package, so you will not need to
  94 manually refresh your foam-extend environment yourself when building individual
  95 ThirdParty packages through the AllMake.stage[1-4] scripts.
  96
  97 The main Allwmake script for the compilation of foam-extend will also take care of
  98 refreshing the environment variable before moving on to the compilation of the
  99 main foam-extend libraries and applications.
 100
 101 However, if you decide to compile the libraries and/or applications manually, or
 102 through the src/Allwmake or applications/Allwmake scripts, YOU MUST MAKE SURE
 103 YOUR ENVIRONMENT VARIABLES FOR THE THIRDPARTY PACKAGES ARE UPDATED FIRST!
 104
 105 In that case, simply resource your bashrc or cshrc file once, before moving on
 106 with the rest of your compilation activities.
 107
 108
 109 3: The building and installation process overview:
 110 --------------------------------------------------
 111 For every ThirdParty packages, this is the basic process we will be going
 112 through when starting the compilation from scratch:
 113
 114     a: Verify in the local "RPM vault" if a RPM file is available for the
 115        required ThirdParty package.
 116
 117     b: If the RPM is available, and the package already installed, then there is
 118        nothing to do for this package, and we proceed with the next package.
 119
 120     c: If the RPM is available, and the package is NOT already installed, then
 121        we simply install it using the RPM and move on to the next package.
 122
 123     d: if the RPM is absent:
 124         1: we verify if the source tarbal is available from the SOURCES "vault"
 125         2: if it is not, we download the tarball using the specified URL.
 126         3: we then proceed with the extraction, patching, configuration,
 127            compilation, RPM generation, TGZ generation and installation of the
 128            package.
 129
 130         Important notices:
 131           - The generated RPM is always used for the installation, not the TGZ file.
 132
 133           - The compressed tarball (.tgz) file is generated for systems where
 134              using rpm for installing packages as a non-root user might be a problem.
 135
 136           - The .rpm files will be located under the directory
 137             $WM_THIRD_PARTY_DIR/rpmBuild/RPMS
 138
 139           - The .tgz files will be located under the directory
 140             $WM_THIRD_PARTY_DIR/rpmBuild/TGZS
 141
 142     e: The default installation root directory is "$WM_THIRD_PARTY_DIR".
 143        This can be overridden though when installing the RPM.
 144
 145     f: Through the modification of the AllMake.stage[1-4] scripts, it is
 146        possible to specify a modified version of a .spec file for a given
 147        package in order to tweak its local compilation or installation.
 148
 149        The modified .spec file will have to be installed under the SPECS
 150        directory, and the corresponding invocation or the command rpm_make in
 151        the AllMake.stage[1-4] file will need to be modified accordingly.
 152
 153
 154 4: Relocating the RPM root installation directory:
 155 --------------------------------------------------
 156
 157 Warning: This section is a bit advanced, and as of yet, I have no evidence that
 158          this feature has ever been used by anybody. So please feel free to skip
 159          this section if you don't need to relocate your ThirdParty packages
 160          installation directory, which you should not have do on most
 161          installation anyway.
 162
 163     a: All the generated RPMs can be relocated, meaning that you can override
 164        the hard-coded root installation directory when using those RPMs for
 165        installation.
 166
 167     b: You can check that the RPM is relocatable by using the command rpm -qip
 168        thePackage.rpm. For example, from the cmake-2.8.3 package generated on one
 169        of my machines, I will get:
 170
 171        > rpm -qip cmake-2.8.3-darwinIntelGccDPOpt.i386.rpm| grep Relocations
 172          Name  : cmake     Relocations: /home/beaudoin/foam/foam-extend-3.1/ThirdParty
 173
 174       The Relocations path is the actual location pointed by the
 175       $WM_THIRD_PARTY_DIR on my virtual machine when I generated the RPM. It is
 176       the indication that the RPM is relocatable. This path will end up being
 177       hardcoded in the RPM because the environment variable was expanded before
 178       generating the RPM.
 179
 180       This is the default root directory where the RPM will install its
 181       "payload". This can be overridden using the 'rpm' command-line parameter
 182       --relocate OLDPATH=NEWPATH .
 183
 184       For example, let's say I want to install my cmake-2.8.3 RPM under the root
 185       directory /tmp/someDir instead. I will need to call the 'rpm' command like
 186       this:
 187
 188       rpm -ivh ./cmake-2.8.3-darwinIntelGccDPOpt.i386.rpm \
 189       --relocate /home/beaudoin/foam/foam-extend-3.1/ThirdParty=/tmp/someDir
 190
 191       Even better, you can dig down the hard-coded path even deeper in order to
 192       relocate the whole installation directory, down to the last hard-coded
 193       subdirectory.
 194       Just specify the whole path when using the --relocate  parameter
 195       So basically, you can install the RPM right under /usr if you want, hence
 196       bypassing the default sequence of package subdirectories I have chosen in
 197       order to stay close to the "traditional" ThirdParty layout.
 198
 199
 200 5: Things to do:
 201 ----------------
 202     a: Testing testing testing. This prototype was tested on the following
 203        platforms:
 204
 205        Centos 5.5 64-bit (RPM based)
 206        Mac OS X 10.6 (Snow Leopard) (non RPM based)
 207        OpenSUSE 11.3 64-bit (RPM based)
 208        RedHat Enterprise Linux 6 64-bit (RPM based)
 209        Ubuntu 10.04 32-bit (non RPM based)
 210        Ubuntu 10.04 64-bit (non RPM based)
 211
 212     b: Maybe adding some RPM dependencies might be useful. I have not explored
 213        this yet.
 214
 215     c: Supplying compilation recipes with the source code for various OSes.
 216        Lots of traffic on the Forum about this. This does not need to be that
 217        complicated.
 218
 219
 220
 221 6: Gotchas and solutions:
 222 -------------------------
 223
 224    1: It was reported that version 5.2.0 of rpm does not work well with the provided scripts.
 225       rpm version 5.2.1 is working nicely.
 226
 227
 228    2: Error messages from rpm:
 229
 230       Problem : error: can't create transaction lock on /var/lock/rpm/transaction
 231
 232       Solution: add the following entry in your file ~/.rpmmacros
 233
 234              %_rpmlock_path %{_dbpath}/__db.000
 235
 236
 237 7: Reporting errors:
 238 --------------------
 239
 240     Please report ThirdParty packages related bugs to the Bug tracking system
 241     for foam-extend-3.1
 242     http://sourceforge.net/apps/mantisbt/openfoam-extend/main_page.php
 243
 244
 245
 246 Martin Beaudoin
 247 Rev 0: 05/2011
 248 Rev 1: 08/2011
 249 Rev 2: 05/2014