               Installation Notes for Regina
               -----------------------------

Please read ALL of these notes before building Regina! If you are
building Regina under AIX 3.x or AIX 4.1.x, ensure you read the
section at the end, titled "Building Regina under AIX"

Installing Regina with root access
----------------------------------
If you have root access on your machine, then simply execute the following
commands from the directory where this file resides:
% ./configure
% make install

Regina can now be used by any user on your machine.

Installing Regina without root access
-------------------------------------
If you don't have root access, then you will need to install Regina into a
location which you have access to; usually your $HOME directory.

Execute the following commands from the directory where this file resides:

% ./configure --prefix=$HOME
% make install

The Regina binaries are now installed in $HOME/bin and the shared libraries
in $HOME/lib.

One final step is required; adding the installation directories into the
appropriate environment variables so that Regina can be run from any directory.

The directory; $HOME/bin needs to added to the PATH environment variable, and
$HOME/lib needs to be added to the system-dependent environment variable that
specifies where shared libraries can be found.

On most platforms, this environment variable is LD_LIBRARY_PATH.
Under AIX this environment variable is LIBPATH.
Under HP-UX this environment variable is SHLIB_PATH.
Under MacOS X this environment variable is DYLIB_LIBRARY_PATH.
Under SGI it seems to be LD_LIBRARYN32_PATH.

Depending on the shell you are running, this is likely to be a command like:
% export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib

Similarly PATH should be set like:
% export PATH=$PATH:$HOME/bin

To ensure that each time you login to your machine and have access to Regina,
add these export commands to the appropriate user login file, like $HOME/.profile
or $HOME/.login.

Other installation options
--------------------------
There are some other configuration options available; run ./configure --help
to see them, but only use options that you understand what effects they have.

What is built
-------------
A normal build of Regina will create the following objects:

 rexx            statically linked Regina Rexx interpreter
 regina          dynamically linked Regina Rexx interpreter
                 (this is the executable to use if you intend using rxfuncadd() )
 libregina.a     static Regina library (also dynamic library under AIX)
 libregina.sl    dynamic Regina library (for HPUX only)
 libregina.so    dynamic Regina library (for all other OS's)
 test1.so|.sl|.a
 test2.so|.sl|.a external function packages provided as examples on how
                 to write external function packages and used by the
                 dynfunc.rexx demo program.
 rxstack         the Regina External Queue daemon
 rxqueue         program to allow non-Regina programs to interface to external
                 queues
 execiser        a test program to exercise the Rexx API
 *.mtb           binary error message files


Building Regina under AIX
-------------------------
This section is only applicable to people building Regina under AIX
3.x and AIX 4.1.x. For later versions of AIX use the procedure above.

To build a version of the Regina library that allows for the dynamic
loading of external function packages, you will need a software package
that emulates the common dlopen() suite of C functions.

This package is dlfcn.tar.gz and should be available from the same place
where you obtained Regina.
dlfcn.tar.gz is written by Helios Software in Germany, and is freely
available.  Please check the documentation that comes with dlfcn.tar.gz
for details on how to build libdl.a and on any restrictions on the use
of dlfcn.tar.gz.

You will first need to build the library, libdl.a using the source code
from dlfcn.tar.gz.

When configuring Regina, there are two extra switches you will require:
--with-dlfcnincdir="directory containing dlfcn.h"
--with-dlfcnlibdir="directory containing libdl.a"

Assuming you downloaded dlfcn.tar.gz and built it in /home/mark/dlfcn, then
the "configure" command for Regina would be:
  configure --with-dlfcnincdir=/home/mark/dlfcn --with-dlfcnlibdir=/home/mark/dlfcn

No checking is done by the configure script to ensure that the header file
and library actually exist in this directory. The first you will know
about it if you specifies the paths incorrectly is a compilation or
linking error.

Building Regina on 64bit Systems
--------------------------------
Regina can be built and run as a 64bit application on 64bit platforms.
Regina can also be built as a 32bit application on 64bit platforms.

It is possible to have both 32 and 64bit Regina libraries installed
on a 64bit platform, provided it has a /usr/lib64 directory in which
64bit libraries are installed.  You can't have both 32bit and 64bit
Regina binaries (ie rexx and regina) installed at the same time.

So, if you have a requirement for Regina support in a third-party
32bit application, the following steps are recommended:
(the following instructions relate to the use of gcc)

1) Build and install 32bit Regina
2) Build and install 64bit Regina

Build and install 32bit Regina on 64bit platform
------------------------------------------------

export CC="gcc -m32"
./configure
make
make install

Build and install 64bit Regina on 64bit platform
------------------------------------------------

./configure --libdir=/usr/lib64
make
make install
