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

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

The default rpm package oxcons-7.00-0.i386.rpm includes the 32-bit
version. The extended rpm package oxcons-7.00-0.x86_64.rpm contains
the 64-bit version. The 64-bit version is invoked with the oxl64
command (in /usr/bin). The 64-bit version requires 64-bit versions
of external dlls. These are available for quadpack, arfima, ssfpack
and emm.


Linux Fedora etc.
--------------------------
Use rpm package oxcons-7.00-0.i386.rpm (or more recent) if possible.
Below I just write ox*.rpm

a) Ox is installed in /usr/share/OxMetrics7/ox
b) oxl command is symbolic link in /usr/bin to 
   /usr/share/OxMetrics7/ox/bin/oxl
   while /usr/share/OxMetrics7/ox/bin/oxl.bin is the Ox executable.
   The 64-bit command is oxl64.
c) RPM requires root access.
d) install Ox as: 
       rpm -ivh ox*.rpm
   or upgrade Ox as: 
       rpm -Uvh ox*.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/oxl_old.

   
Linux Ubuntu/Debian
-------------------
a) Ox is installed in /usr/share/OxMetrics7/ox
b) oxl command is symbolic link in /usr/bin to 
   /usr/share/OxMetrics7/ox/bin/oxl
   while /usr/share/OxMetrics7/ox/bin/oxl.bin is the Ox executable.
   The 64-bit command is oxl64.
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/oxl5 if you already have Ox 5, and wish
   to keep it.
d) issue the command in a local folder: 
       sudo alien -i -c ox*.rpm
   Under 64-bit linux there may be an error message that amd64 is not in the
   package. However, it seems to install fine.
e) When I tried this for 64-bit Ubuntu, installation was to the current folder,
   so must be moved to /usr/share/OxMetrics7 (again as sudo; this is not 
   necessary under 32-bit Ubuntu).


Mac OS-X (Darwin)
-----------------
a) Use the installer package (.pkg.zip), Ox is installed to
   /Applications/OxMetrics7/ox

   
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.7.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.7.2.0  7 is the major, and 2.0 the minor
    version number. The executable only looks for a file matching
    the major version number (libox.so.7).
    A symbolic link is required to resolve the search:
        rm libox.so.7
        ln -s libox.so.7.2.0 libox.so.7
    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.7.2.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.7 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. 

(4) set the OX7PATH 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 OX7PATH paths
    3. Search along OX7PATH 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 OX7PATH 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, except for OS X).

	DLLs for different platforms can be kept separate by using _64 and
	platform-specific suffix. For example, Ox will try first one of:
		arfima.dll			 Windows 32-bit
		arfima_64.dll		 Windows 64-bit
		arfima.so			 Linux 32-bit
		arfima_64.so		 Linux 64-bit
		arfima_osx.so		 OS X 32-bit
		arfima_sparc.so		 Solaris on Sparc, 32-bit
		arfima_sunx86.so	 Solaris on x86, 32-bit
		arfima_sparc_64.so	 Solaris on Sparc, 64-bit
		arfima_sunx86_64.so	 Solaris on x86, 64-bit
	using the search method described above. If that fails, the search is
	done with just arfima.

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 OX7PATH variable:
        OX7PATH="$HOME/ox/include:$HOME/ox"; export OX7PATH

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