**********
Installing
**********

Instructions for the installation of the PySOAR package are below.  In
order to install PySOAR, several other packages have to be installed
as well including python, PyRAF, and IRAF.  Descriptions and links to
each of those packages are included under dependencies.  All of the
dependent programs are available on the SOAR `ftp site
<ftp://www.ctio.noao.edu/~fraga/pub/ftp/>`_.

Prerequisites
=============
* This package requires `IRAF <http://iraf.noao.edu/>`_ version 2.12.2 or later.
* It also requires `PyRAF <http://www.stsci.edu/resources/software_hardware/pyraf>`_ version 1.7.1 or later.
    * tcl: Version 8.3.5 or higher
    * tk:  v8.3.5 or higher
    * qt: Version 4.0 or later
    * python: v2.5.1 or higher
    * readline: v4.3
    * Pmw: v1.2
    * libf2c

* Additional required python packages:
    * `matplotlib <http://matplotlib.sourceforge.net/>`_: v0.91 or later
    * `pyfits <http://www.stsci.edu/resources/software_hardware/pyfits>`_: v1.3
    * `numpy <http://numpy.scipy.org/>`_: v1.04 or later
    * `scipy <http://www.scipy.org/>`_: v0.5.2 or later
    * `pyqt4 <http://www.riverbankcomputing.co.uk/software/pyqt/download>`_: v4.6 or later
    * `sphinx <http://sphinx.pocoo.org/>`_ (optional): to compile the documentation

Downloading
===========

The PySOAR user package v0.01 was released on ? March 2012 and can be
downloaded `here <www.ctio.noao.edu>`_.  `Release notes
<www.soartelescope.org/soar-data-reduction/pysoar-users-package/release-notes/>`_
are available.

Installation of the PySOAR package
==================================
To install the package as root, create a directory to contain the PySOAR external package files.
This directory should be outside the IRAF directory tree and must be owned by the IRAF account.
In the following example, this root directory is named::

  /iraf/extern/pysoar

Make the appropriate file name substitutions for your site.

#. Log in as IRAF and edit the *extern.pkg* file in the *hlib*
   directory to define the package to the CL.
   From the IRAF account, outside the CL, you can move to this directory with the commands::

     % cd /iraf/iraf/unix/hlib/

   Define the environment variable soar to be the pathname to the soar
   root directory. UNIX pathnames must be terminated with a ``/``.
   Edit *extern.pkg* to include::

     reset pysoar     = /iraf/extern/pysoar/
     task  pysoar.pkg = pysoar$pysoar.cl

   Near the end of the *hlib$extern.pkg* file, update the definition of *helpdb*
   so it includes the soar help database, copying the syntax already used
   in the string. Add this line before the line containing a closing quote::
        
     ,pysoar$lib/helpdb.mip\

#. Change directories to the PySOAR root directory created above
   and unpack the download file *pysoar.tar.gz*::

     % cd /iraf/extern/pysoar/
     % tar zxvf <path>/pysoar.tar.gz

   where ``<path>`` is the relative path from ``/iraf/extern/pysoar`` to the downloaded file.

#. To install the package under your home directory, unpack the
   downloaded file *pysoar.tar.gz*.
   Then add the following line to your user *login.cl*::
    
     reset pysoar   = "[your path]"
     task  pysoar.pkg   = "pysoar$pysoar.cl"
     reset helpdb    = (envget("helpdb") // ",pysoar$lib/helpdb.mip")

#. Finally to build the documentation
   make sure you have *sphinx* installed and execute::

     % cd /iraf/extern/pysoar/doc
     % make html

   The start point for the documentation is in ``build/index.html``.
   For a manual in *pdf* format (you need LaTeX as well) use::

     % cd /iraf/extern/pysoar/doc
     % make latex
     % cd /iraf/extern/pysoar/doc/build/latex
     % pdflatex PySOAR.tex
     % pdflatex PySOAR.tex

The manual will than be in ``PySOAR.pdf``