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 To install Regina, you first need to configure it.  This is done by
   9 executing the configure script provided in this archive.
  10
  11 Generally all you need to run is "configure", but there are some
  12 options that can be passed to the configure script; use
  13 "configure --help" to view them.
  14
  15 Once the configure script has been run, you can then type "make".
  16 This will create the following objects:
  17
  18  rexx            statically linked Regina Rexx interpreter
  19  regina          dynamically linked Regina Rexx interpreter
  20                  (this is the executable to use if you intend using rxfuncadd() )
  21  libregina.a     static Regina library (also dynamic library under AIX)
  22  libregina.sl    dynamic Regina library (for HPUX only)
  23  libregina.so    dynamic Regina library (for all other OS's)
  24  execiser        program to exercise Regina internals
  25  test1.so|.sl|.a
  26  test2.so|.sl|.a external function packages provided as examples on how
  27                  to write external function packages and used by the
  28                  dynfunc.rexx demo program.
  29
  30 Once you have Regina compiled, it can then be installed.  By default, the
  31 Regina executables will be installed into /usr/local/bin and the libraries
  32 and external function packages (*.so|.sl|.a) will be installed into
  33 /usr/local/lib.  The base path "/usr/local" can be changed by adding the
  34 --prefix=path (where path is the base path) to the configure command.
  35 eg. to install Regina into /opt/bin and /opt/lib, configure --prefix=/opt ...
  36
  37 On most platforms, it is necessary to include the directory where shared
  38 libraries (including *.so|.sl|.a) reside, to the LD_LIBRARY_PATH
  39 environment variable.  Under AIX this environment variable is LIBPATH.
  40 Under HP-UX this environment variable is SHLIB_PATH.
  41 Under SGI seems to be LD_LIBRARYN32_PATH.
  42
  43 Building Regina under AIX
  44 -------------------------
  45 This section is only applicable to people building Regina under AIX
  46 3.x and AIX 4.1.x.
  47
  48 To build a version of the Regina library that allows for the dynamic
  49 loading of external function packages, you will need a software package
  50 that emulates the common dlopen() suite of C functions.
  51
  52 This package is dlfcn.tar.gz and should be available from the same place
  53 where you obtained Regina.
  54 dlfcn.tar.gz is written by Helios Software in Germany, and is freely
  55 available.  Please check the documentation that comes with dlfcn.tar.gz
  56 for details on how to build libdl.a and on any restrictions on the use
  57 of dlfcn.tar.gz.
  58
  59 You will first need to build the library, libdl.a using the source code
  60 from dlfcn.tar.gz.
  61
  62 When configuring Regina, there are two extra switches you will require:
  63 --with-dlfcnincdir="directory containing dlfcn.h"
  64 --with-dlfcnlibdir="directory containing libdl.a"
  65
  66 Assuming you downloaded dlfcn.tar.gz and built it in /home/mark/dlfcn, then
  67 the "configure" command for Regina would be:
  68   configure --with-dlfcnincdir=/home/mark/dlfcn --with-dlfcnlibdir=/home/mark/dlfcn
  69
  70 No checking is done by the configure script to ensure that the header file
  71 and library actually exist in this directory. The first you will know
  72 about it if you specifies the paths incorrectly is a compilation or
  73 linking error.