regina/INSTALL

   1                Installation Notes for Regina
   2                -----------------------------
   3
   4 Please read ALL of these notes before building Regina! If you are
   5 building Regina under AIX 3.x or AIX 4.1.x, ensure you read the
   6 section at the end, titled "Building Regina under AIX"
   7
   8 Installing Regina with root access
   9 ----------------------------------
  10 If you have root access on your machine, then simply execute the following
  11 commands from the directory where this file resides:
  12 % ./configure
  13 % make install
  14
  15 Regina can now be used by any user on your machine.
  16
  17 Installing Regina without root access
  18 -------------------------------------
  19 If you don't have root access, then you will need to install Regina into a
  20 location which you have access to; usually your $HOME directory.
  21
  22 Execute the following commands from the directory where this file resides:
  23
  24 % ./configure --prefix=$HOME
  25 % make install
  26
  27 The Regina binaries are now installed in $HOME/bin and the shared libraries
  28 in $HOME/lib.
  29
  30 One final step is required; adding the installation directories into the
  31 appropriate environment variables so that Regina can be run from any directory.
  32
  33 The directory; $HOME/bin needs to added to the PATH environment variable, and
  34 $HOME/lib needs to be added to the system-dependent environment variable that
  35 specifies where shared libraries can be found.
  36
  37 On most platforms, this environment variable is LD_LIBRARY_PATH.
  38 Under AIX this environment variable is LIBPATH.
  39 Under HP-UX this environment variable is SHLIB_PATH.
  40 Under MacOS X this environment variable is DYLIB_LIBRARY_PATH.
  41 Under SGI it seems to be LD_LIBRARYN32_PATH.
  42
  43 Depending on the shell you are running, this is likely to be a command like:
  44 % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib
  45
  46 Similarly PATH should be set like:
  47 % export PATH=$PATH:$HOME/bin
  48
  49 To ensure that each time you login to your machine and have access to Regina,
  50 add these export commands to the appropriate user login file, like $HOME/.profile
  51 or $HOME/.login.
  52
  53 Other installation options
  54 --------------------------
  55 There are some other configuration options available; run ./configure --help
  56 to see them, but only use options that you understand what effects they have.
  57
  58 What is built
  59 -------------
  60 A normal build of Regina will create the following objects:
  61
  62  rexx            statically linked Regina Rexx interpreter
  63  regina          dynamically linked Regina Rexx interpreter
  64                  (this is the executable to use if you intend using rxfuncadd() )
  65  libregina.a     static Regina library (also dynamic library under AIX)
  66  libregina.sl    dynamic Regina library (for HPUX only)
  67  libregina.so    dynamic Regina library (for all other OS's)
  68  test1.so|.sl|.a
  69  test2.so|.sl|.a external function packages provided as examples on how
  70                  to write external function packages and used by the
  71                  dynfunc.rexx demo program.
  72  rxstack         the Regina External Queue daemon
  73  rxqueue         program to allow non-Regina programs to interface to external
  74                  queues
  75  execiser        a test program to exercise the Rexx API
  76  *.mtb           binary error message files
  77
  78
  79 Building Regina under AIX
  80 -------------------------
  81 This section is only applicable to people building Regina under AIX
  82 3.x and AIX 4.1.x. For later versions of AIX use the procedure above.
  83
  84 To build a version of the Regina library that allows for the dynamic
  85 loading of external function packages, you will need a software package
  86 that emulates the common dlopen() suite of C functions.
  87
  88 This package is dlfcn.tar.gz and should be available from the same place
  89 where you obtained Regina.
  90 dlfcn.tar.gz is written by Helios Software in Germany, and is freely
  91 available.  Please check the documentation that comes with dlfcn.tar.gz
  92 for details on how to build libdl.a and on any restrictions on the use
  93 of dlfcn.tar.gz.
  94
  95 You will first need to build the library, libdl.a using the source code
  96 from dlfcn.tar.gz.
  97
  98 When configuring Regina, there are two extra switches you will require:
  99 --with-dlfcnincdir="directory containing dlfcn.h"
 100 --with-dlfcnlibdir="directory containing libdl.a"
 101
 102 Assuming you downloaded dlfcn.tar.gz and built it in /home/mark/dlfcn, then
 103 the "configure" command for Regina would be:
 104   configure --with-dlfcnincdir=/home/mark/dlfcn --with-dlfcnlibdir=/home/mark/dlfcn
 105
 106 No checking is done by the configure script to ensure that the header file
 107 and library actually exist in this directory. The first you will know
 108 about it if you specifies the paths incorrectly is a compilation or
 109 linking error.
 110
 111 Building Regina on 64bit Systems
 112 --------------------------------
 113 Regina can be built and run as a 64bit application on 64bit platforms.
 114 Regina can also be built as a 32bit application on 64bit platforms.
 115
 116 It is possible to have both 32 and 64bit Regina libraries installed
 117 on a 64bit platform, provided it has a /usr/lib64 directory in which
 118 64bit libraries are installed.  You can't have both 32bit and 64bit
 119 Regina binaries (ie rexx and regina) installed at the same time.
 120
 121 So, if you have a requirement for Regina support in a third-party
 122 32bit application, the following steps are recommended:
 123 (the following instructions relate to the use of gcc)
 124
 125 1) Build and install 32bit Regina
 126 2) Build and install 64bit Regina
 127
 128 Build and install 32bit Regina on 64bit platform
 129 ------------------------------------------------
 130
 131 export CC="gcc -m32"
 132 ./configure
 133 make
 134 make install
 135
 136 Build and install 64bit Regina on 64bit platform
 137 ------------------------------------------------
 138
 139 ./configure --libdir=/usr/lib64
 140 make
 141 make install