Linux/Unix Installation Notes
=============================

General
--------------------------

The default rpm package ox-4.00-1.i386.rpm includes the 32-bit version.

The extended rpm package ox-4.00-1.x86_64.rpm includes the 32-bit and
the 64-bit versions. The 64-bit version is invoked with the oxl64
command (in /usr/bin), and is still somewhat experimental. The 64-bit
version requires 64-bit versions of external dlls. These are available
for quadpack, arfima, ssfpack and emm.


Linux openSUSE/Fedora etc.
--------------------------
Use rpm package ox-4.00-1.i386.rpm (or more recent) if possible.

a) Ox is installed in /usr/local/lib/ox-4.00
b) oxl command is symbolic link in /usr/bin to 
   /usr/local/lib/ox-4.00/bin/oxl
   while /usr/local/lib/ox-4.00/bin/oxl.bin is the Ox executable.
   Rename /usr/bin/oxl to /usr/bin/oxl3 if you already have Ox 3, and wish
   to keep it.
c) RPM installation requires root access.
d1)When downloading the rpm, Firefox may offer to open with `Install Software',
   which should install Ox. Otherwise:
d2)open a terminal window and install Ox as: 
       rpm -ivh ox-4.00-1.i386.rpm
   or upgrade Ox as: 
       rpm -Uvh ox-4.00-1.i386.rpm
e) When upgrading, the installation may warn that /usr/bin/oxl
   already exists. To avoid this, uninstall the old Ox first, or
   rename the file to /usr/bin/oxl400.

   
Linux Ubuntu/Debian
-------------------
a) Ox is installed in /usr/local/lib/ox-4.00
b) oxl command is symbolic link in /usr/bin to 
   /usr/local/lib/ox-4.00/bin/oxl
   while /usr/local/lib/ox-4.00/bin/oxl.bin is the Ox executable.
b) Use alien to install the rpm. Alien is not installed by default in Ubuntu,
   so install this first.
c) Rename /usr/bin/oxl to /usr/bin/oxl3 if you already have Ox 3, and wish
   to keep it.
d) issue the command in a local folder: 
       sudo alien -i ox-4.00-1.i386.rpm
   Under 64-bit linux there is an error message that amd64 is not in the
   package. However, it seems to install fine.
e) When I tried this, installation was to the current folder, so must be
   moved (again as sudo; this may not be necessary under 32-bit Ubuntu)
   sudo cp -r ./ox-4.00/usr/local/lib/* /usr/local/lib 
   sudo cp -r ./ox-4.00/usr/bin/* /usr/bin


Mac OS-X (Darwin)
-----------------
a) Go superuser (sudo -s)
b) Create /usr/local/lib/ox-4.00
c) Copy oxbas400.zip to this folder, and unzip from there.
   This will create ox/include, ox/samples etc.
d) Create /usr/local/lib/ox-4.00/bin
   and unzip the contents of oxosx400.zip into this folder.
e) Create a symbolic link from libox.4.dylib to libox.4.0.0.dylib.
f) Create a symbolic link from /usr/bin/oxl to
   /usr/local/lib/ox-4.00/bin/oxl.
g) you may have to make the files in /usr/local/lib/ox-4.00/bin
   executable using chmod +x.
h) copy oxosxdll.zip to /usr/local/lib/ox-4.00
   and unzip from there.
i) optionally copy oxdev400.zip to
	/usr/local/lib/ox-4.00 and unzip from there.

   
Sun Solaris
-----------
a) Go superuser (su)
b) Create /usr/local/lib/ox-4.00
c) Copy oxbas400.zip to this folder, and unzip from there.
   This will create ox/include, ox/samples etc.
d) Create /usr/local/lib/ox-4.00/bin
   and unzip the contents of oxsun400.zip into this folder.
f) Create a symbolic link from /usr/bin/oxl to
   /usr/local/lib/ox-4.00/bin/oxl.
g) you may have to make the files in /usr/local/lib/ox-4.00/bin
   executable using chmod +x.
h) copy oxsundll.zip to /usr/local/lib/ox-4.00
   and unzip from there.
i) optionally copy oxdev400.zip to
	/usr/local/lib/ox-4.00 and unzip from there.

   
Older zip file installations
----------------------------
In these, bin/oxl is the executable (instead of bin/oxl.bin),
and the script bin/oxl is not provided.


Unix installation remarks (some differ between shells)
------------------------------------------------------
(0) Dynamic link libraries have the .so extension under Unix,
    except for HP-UX, which uses .sl, and OS-X (Darwin) which
	uses .dylib. OS-X distinguishes with between dynamic-link
	libraries that are dynamically linked at startup (.dylib), and
	modules that can be loaded programmatically when the program is
	running (bundles, Ox uses the .so extension for these).

(1) Ox is dynamically linked:
    libox.so.4.0.0     is the (dynamically linked) Ox library
    oxl                (or oxl.bin) is the executable which links to it.
    Normally, step (3) and (4) below would be added to a startup script

(2) version numbers:
    In (e.g.) libox.so.4.1.0  4 is the major, and 10.0 the minor
    version number. The executable only looks for a file matching
    the major version number (libox.so.4).
    A symbolic link is required to resolve the search:
        rm libox.so.4
        ln -s libox.so.4.0.0 libox.so.4
    This numbering system is not used for HPUX and AIX. Under HPUX
    the DLL is called oxl.sl, and no symbolic link is required.
    Under AIX the shared library file is called libox.a.
	Under OS-X it is called oxl.4.0.0.dylib.
        
(3) library search paths:
    LD_LIBRARY_PATH is used to search for the library file when
    the file is in a non-standard location. This must be set to
    the directory where libox.so.4 is, unless it has been moved to
    standard directory which is searched by default.
    (HPUX uses SHLIB_PATH, AIX LIBPATH and OS-X DYLD_LIBRARY_PATH
	or DYLD_FALLBACK_LIBRARY_PATH.)

    Check the man pages of the loader (rld,ld,loader) if you have
    problems. If you have permission, you can copy the libox.so.4.0.0
    file to /usr/local/lib/, or a directory which is in the standard
    search path.

(4) set the OX4PATH variable to allow Ox to find include files, e.g. to
        "$HOME/ox/include:$HOME/ox"
    Note that setting environment variables is shell specific, see below.

(5) The threes example shows how to create and call a dynamic link
    library. Run  make -f threes.mak  to compile threes.so
    (the header file oxexport.h and dependencies must be in the search
    path). On some platforms there may be unresolved messages from the
    linker, which may be ignored.
    Then run
        oxl threes
    to see if it works.
    The dynamic linker must be able to find threes.so, also see (2),(6).

(6) When adding a DLL which is to be used from Ox, Ox will try to
    locate it in the following way:
    1. Try directly
    2. Search along OX4PATH paths
    3. Search along OX4PATH relative to #import statements which
       have a path component.
    4. Try package/dll_name directory (but only if no
       path is used in the extern statement).

    For example, when the declaration is:
        extern "arfima,FnFracSigma" fracsigma(....);
    and arfima.oxo has:
        #import <modelbase>
        #import <lib/testres>
    and somewhere else is:
        #import <packages/arfima/arfima>
    moreover, the OX4PATH is set to $HOME/ox/include:$HOME/ox
    
    Then Ox will try:
    1.  ./arfima.so
    2a. $HOME/ox/include/arfima.so
     b. $HOME/ox/arfima.so
    3a. $HOME/ox/include/lib/arfima.so
     b. $HOME/ox/lib/arfima.so
     c. $HOME/ox/include/packages/arfima/arfima.so
     d. $HOME/ox/packages/arfima/arfima.so
    4a. $HOME/ox/include/packages/arfima/arfima.so
     b. $HOME/ox/packages/arfima/arfima.so
    
    So, when Ox is loading a library through the extern statement,
    the LD_LIBRARY_PATH is not used.
    Also note that under Windows, the operating system automatically
    searches along the path statement, which does not happen under
    Unix. (Of course, Unix is also case-sensitive). 

NB1 Setting environment variables:
    For bash shells:
    to show contents of LD_LIBRARY_PATH environment variable:
        echo $LD_LIBRARY_PATH
    to set to a directory, e.g. to:
        LD_LIBRARY_PATH="$HOME/ox/bin"; export LD_LIBRARY_PATH
    to append the ox/bin directory:
        LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$HOME/ox/bin"; export LD_LIBRARY_PATH
    to set the OX4PATH variable:
        OX4PATH="$HOME/ox/include:$HOME/ox"; export OX4PATH

    Other shells may use setenv/printenv:
    to show contents of LD_LIBRARY_PATH environment variable:
        printenv $LD_LIBRARY_PATH
    to set to a directory, e.g. to:
        setenv LD_LIBRARY_PATH "$HOME/ox/bin"
    to set the OX4PATH variable:
        setenv OX4PATH "$HOME/ox/include:$HOME/ox"
        
    Or e.g. on AIX you may need to add /usr/lib, as well as the
    current directory:
        LIBPATH=".:/usr/lib:$HOME/ox/bin"; export LIBPATH


NB2 File mode, it might be necessary to set the file mode to
    executable, for example:
        chmod +x oxl

NB3 On some systems, when in the bin directory, it is necessary
    to run ox as ./oxl instead of just oxl

NB5 I was unable to link DLLs on the Sun which was using Fortran
    code involving complex*16 (the version with reals only worked
    fine).
    
NB6 When developing DLLs for Ox, the ldd command can sometimes
    help with to find out why a DLL does not link.
    
NB7 Use: find / -name xxx
    to search for xxx from the root.
