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

Linux Redhat/Mandrake etc.
--------------------------
Use rpm package ox-3.40-1.i586.rpm (or more recent) if possible.

a) Ox is installed in /usr/local/lib/ox-3.40
b) oxl command is symbolic link in /usr/bin to 
   /usr/local/lib/ox-3.40/bin/oxl
   while /usr/local/lib/ox-3.40/bin/oxl.bin is the Ox executable.
c) RPM requires root access.
d) install Ox as: 
       rpm -ivh ox-3.40-1.i586.rpm
   or upgrade Ox as: 
       rpm -Uvh ox-3.40-1.i586.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/oxl330.

   
Linux Debian
------------
For Debian Linux, as superuser use the command: 
       alien ox-3.40-1.i586.rpm
Then use the dpkg -i command to install Ox.


Sun Solaris and Mac OS-X (Darwin)
---------------------------------
a) Go superuser (su or sudo -s on OS-X)
b) Create /usr/local/lib/ox-3.40
c) Copy oxbas340.zip to this folder, and unzip from there.
   This will create ox/include, ox/samples etc.
d) Create /usr/local/lib/ox-3.40/bin
   and unzip the contents of oxsun340.zip (oxosx340.zip
   respectively) into this folder.
e) Create a symbolic link from oxl.3.dylib to oxl.3.4.0.dylib.
f) Either copy /usr/local/lib/ox-3.40/bin/oxl to /usr/bin
   or create a symbolic link to this file from /usr/bin.
g) copy oxsundll.zip (oxosxdll.zip) to /usr/local/lib/ox-3.40
   and unzip from there.
h) optionally copy oxdev340.zip to
	/usr/local/lib/ox-3.40 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:
    oxl.so.3.40.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.) oxl.so.3.40.0  3 is the major, and 40.0 the minor
    version number. The executable only looks for a file matching
    the major version number (oxl.so.3).
    A symbolic link is required to resolve the search:
        rm oxl.so.3
        ln -s oxl.so.3.40.0 oxl.so.3
    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.3.4.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 oxl.so.3 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 oxl.so.3.40.0
    file to /usr/local/lib/, or a directory which is in the standard
    search path.

(4) set the OX3PATH 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 OX3PATH paths
    3. Search along OX3PATH 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 OX3PATH 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 OX3PATH variable:
        OX3PATH="$HOME/ox/include:$HOME/ox"; export OX3PATH

    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 OX3PATH variable:
        setenv OX3PATH "$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.
