// -*- text -*-
// $RCSfile: README,v $
// $Revision: 1.25 $
// $Author: langer $
// $Date: 2009-01-26 19:38:36 $

Congratulations!  You are reading the README file for a software
package you downloaded!  You are now officially an *advanced* software
installer.

This is the README file for OOF2, describing how to build and install
it with the Python distutils utility.  This version does *not* contain
a configure script or Makefile.

This README file is for OOF2 version 2.0.4 or (maybe) later.

Installation:
------------

Installation is similar to other Python libraries.  If your system is
well-set-up, and has the required libraries, there should be no
difficulties.

The executive summary of steps is:

> tar -xzf oof-<version>.tgz
> cd oof-<version>
> python setup.py build
> python setup.py install

but please read the rest of this file before proceeding.

If something goes wrong, your system adminstrator may be able to help
you, or you can contact the oof developers at oof_manager@nist.gov.
It's diagnostically useful to include all the output from setup.py.

OOF2 has been built and tested on Debian Linux, Redhat Linux, SGI, and
Macintosh OS X.

Details:
-------

0. What You Should Already Have:

   A computer running a variant of the Unix operating system,
   including Linux and Macintosh OS X, and an X11 server.  OOF2
   currently does *not* run on Microsoft Windows.
   
   The following external programs and libraries must be present
   before you can run OOF2.  To compile OOF2 from sources, you will
   also require the header files ("includes") associated with these
   programs and libraries.  These are usually available as part of a
   "development" version of the library software.

    Python (2.3 or later)   http://www.python.org 
    Magick++                http://www.imagemagick.org/www/Magick++/index.html
    gtk+-2.0 (2.6 or later) http://www.gtk.org/download/   
    libgnomecanvas2   http://directory.fsf.org/graphics/misc/libgnomecanvas.html
    pygtk2 (2.6 or later)   http://www.pygtk.org
   *swig 1.1 build 883      http://www.swig.org/download.html

   Macintosh OS X users will need to install an X11 server.  Apple's
   X11.app is available as an option when installing OS X 10.3 or
   later. It may be obtained from
   http://www.apple.com/macosx/features/x11/.  Users of earlier
   versions of OS X will need to get a server elsewhere.

   You should also have the ability to run lapack and the "blas" basic
   linear algebra subroutines.  On Macintosh OS X, they are built in
   to the vecLib framework, and no special libraries are required.  On
   Linux and commercial Unix systems, they may have to be installed,
   and you may require headers.

   *We're using an old version of swig because it was the stable
   version at the time we started working on OOF2.  The current
   version will *not* work with OOF2.  We will upgrade to a modern
   version of swig in a later release.  Because of the
   obscurity/antiquity of swig 1.1 build 883, this package is
   optional.  The swig output is included with the OOF2 distribution.
   However, if you want to add your own extensions to OOF2, you will
   need swig.

1. What You Got From Us:
   
   The file "oof2-<version>.tar.gz".

Procedure:
---------

   (Macintosh OS X users can install OOF2 from either a Terminal or
   xterm window, or the equivalent.)

0. Unpack

   Unpack the .tar.gz file.  The usual way is to run "tar -xzf" on the
   file you want to unpack.  This will create a subdirectory named
   "oof2-<version>" in the directory where you run tar.

1. Build the OOF2 libraries and Python extension modules

   Switch to the newly-created directory, and run

     % python setup.py build

   If you do not want the script to run swig (for example, if you
   don't have swig 1.1 build 883 installed), append "--skip-swig" to
   the build command:

     % python setup.py build --skip-swig

   *IMPORTANT*: If you do not have swig, or do not have the correct
   version, you must build and install OOF2 simultaneously.  Read the
   NOTE in section 2, below.

   The build_ext command will create a "build" subdirectory in the top
   OOF2 directory.  Within "build" it will create a subdirectory with
   a system-dependent name.  (This will *not* conflict with any build
   directory that you might have created with the old configure/make
   method of building OOF2.)

1.1 Getting more control over the build

   You can ignore this section unless something went wrong when
   building OOF2 in step 1.  setup.py tries to be intelligent about
   choosing options, but it's not perfect.

   The distutils "build" command actually runs a bunch of separate
   subcommands, each of which has its own options.  The relevant
   subcommands are "build_shlib", "build_ext", "build_scripts", and
   "build_py".  "build_shlib" builds the shared libraries,
   liboof2common.so, etc, that contain most of the low-level OOF2
   machinery. "build_ext" builds the OOF2 Python extension modules
   that provide the interface betweeen C++ and Python.  "build_py"
   copies the Python files from the source directory to the build
   directory, and "build_scripts" copies the start-up script into the
   build directory and makes it executable.  OOF2 installers will
   probably only have to worry about "build_shlib" and "build_ext".

   The four commands must be run in order: build_shlib must precede
   build_ext, and build_ext must precede build_py.

   Each command can be run separately, for example

     % python setup.py build_ext

   or in combination

     % python setup.py build_shlib build_ext

   and options can be provided to each one
  
    % python setup.py build_shlib --debug build_ext --include_dirs=/sw/include

   You can see the full set of options by running

     % python setup.py --help <command name>

   Here are the options most likely to be useful:

   For "build_shlib" or "build":

   --library-dirs    Specify a non-standard location for libraries.
                     Multiple directories should be separated by
                     colons, like this:
                       --library-dirs=/strange/spot:/out/of/theway

   --libraries       Specify libraries to load. Due to a bug in
                     distutils, it's only possible to specify a single
                     library. For example
                        --libraries=abc
		     will load libabc.so.  If you need to load more
                     than one library in this way, please contact us.
      
   --blas-libraries  Specify libraries to use for blas and lapack.
                     Multiple library names should be separated by
                     spaces, like this:
                        --blas-libraries="myblas mylapack"

   --blas-link-args  Specify additional link arguments required by
                     blas and lapack, for example:
		        --blas-link-args="-faltivec -framework vecLib"

   For "build_ext" or "build":

   --skip-swig       Don't run swig.  The oof2 distribution includes
                     the swig output files, so it's not necessary to
                     run swig unless you've changed the swig input
                     files.  oof2 also requires an old version of swig
                     (1.1 build 883), and if you accidentally run a
                     newer version you will corrupt the distributed
                     files.  If that happens, unpack the tar file
                     again (to get a clean copy) and make sure to
                     specify --skip-swig when you run build or
                     build_ext.  See the note in item 2, below. You
		     *must* run the build and install steps
		     simultaneously if you use --skip-swig.

   --with-swig       Specify the name of the swig executable.  Use
                     this if, for example, you have both swig 1.3 and
                     swig 1.1 installed, and you've renamed swig 1.1 to
                     "oldswig".  Then you'd use
		         python setup.py build --with-swig=oldswig

   --swig, --swig-cpp, --swig-opts
                     Do NOT use these options.  They will be ignored.
                     They're leftover from the raw distutils swigging
                     mechanism, which we don't use.

   The following arguments can appear anywhere after "setup.py" in the
   command line, and apply to both the build and install steps.  Tf
   you run the build and install steps separately, you must provide
   these arguments in *both* steps if you provide them in one.

   --disable-gui     Don't include any components of the graphical user
                     interface.  When this option is used, it's not
                     necessary to have the gtk, pygtk, or
                     libgnomecanvas libraries installed.

   [The --enable-orientationmap argument is no longer needed, or
   accepted.  Orientation map handling is always enabled, as of
   version 2.0.4a3.]

2. Install

   To install OOF2, run

   % python setup.py install

   This will install OOF2 in the standard location for Python
   extensions on your system.  This is good, because then you won't
   have to do anything special to get OOF2 to run.  It's also bad,
   because unless you are the system administrator, you probably don't
   have permission to install anything in that directory.  You have
   two options:

    a) Get a system administrator to run the installation step.

    b) Tell distutils to install oof2 in a different place, like this:

          % python setup.py install --prefix=<prefix>

    where <prefix> is a directory that you can write to.  The default
    value of <prefix> is usually /usr/local.  On OS X it may be
    something like /Library/Frameworks/Python.framework/Versions/2.3
    if you're using the system Python, or /sw if you're using fink's
    Python.

    The installation procedure will create an executable script called
    "oof2" in <prefix>/bin, a bunch of shared libraries called
    "liboof2*.so" or "liboof2*.dylib" in <prefix>/lib, a directory
    called "oof2" in <prefix>/lib/python2.x/site-packages (where 2.x
    is your python version number), and some example files in
    <prefix>/share/oof2/examples. 

    (It's possible to use --home=<home> instead of --prefix when
    installing oof2.  The only difference is that --home will put the
    python libraries in <home>/lib/python instead of
    <prefix>/lib/python2.x/site-packages.)

    NOTE: If you need to use --skip-swig (see item 1) you will have to
    run the build and install commands together, like this:

          % python setup.py build --skip-swig install --prefix=<prefix>

    adding in any other build and install arguments you want to use.
    If you don't do this, and run install separately, it will think
    that the swig files are out of date and will try to run swig.  If
    that happens, you'll get lots of compilation errors.  To correct
    the problem, you'll have to restore the contents of the SRC/SWIG
    directory by unpacking the distributed .tar.gz file again.

2.1. Set environment variables

    If <prefix>/bin is not in your Unix command path, you'll need to
    add it to the PATH environment variable, or create a symbolic link
    from a directory that is in your path (or start OOF2 the hard way
    by by typing <prefix>/bin/oof2).  (Typing "echo $path" will print
    the current value of your path.  The method for setting
    environment variables depends on which Unix shell you're using.)

    If <prefix>/lib is not in the list of directories that the dynamic
    linker searches for libraries, you'll have to add it by setting
    the LD_LIBRARY_PATH environment variable.  This should *not* be
    necessary on Macintosh OS X.

    If <prefix>/lib/python2.x/site-packages is not in your Python
    path, you'll have to add it to the PYTHONPATH environment
    variable.   (Running the command
       % python -c "import sys; print sys.path"
    will print your Python path.)

Running OOF2:
------------

At this point, you should have an executable file named "oof2" in a
bin directory in your execution path.  You can now simply type "oof2"
at your shell prompt, and OOF2 will start up.  (Macintosh OS X users
will have to start X11 before starting OOF2.  Then OOF2 can be started
in an xterm window, or in a Terminal window if the DISPLAY environment
variable has been set correctly, probably to ":0.0".)

OOF also has many options, and you can get a summary of them
by typing "oof2 --help".

By default, OOF runs in graphics mode, opening a couple of
windows to get you started.  If you don't want this, you can use
the "--text" option to run it in command-line mode.