.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................


Useful free software
=====================

To use our most recent shipboard ADCP processing software, you will
need a recent version of `Python <http://www.python.org/>`_

    Python notes for various systems:

    * Linux: you probably already have it; typical Linux distributions
      install it by default, and any that do not will at least have it
      available as an installable package.

    * Solaris or Irix, then it may be up to your sysadmin to install
      Python, and you may need to prompt them to update whatever is
      there.

    * OSX: Although a version is included with OSX, it is recommended
      that you install the version from python.org.  It can coexist
      happily with the OSX-included version, allowing you to install
      whatever additional python packages you need without interfering
      with the system version.

    * Windows: Again, install the version from python.org.
      Then download and install the `Python Windows Extensions
      <http://sourceforge.net/projects/pywin32>`_ which adds
      the mechanism we use to communicate between python and
      Matlab.


Rich Pawlowicz wrote `m_map <http://www2.ocgy.ubc.ca/%7Erich/map.html>`_,
an excellent, free Matlab mapping toolbox
that we use extensively. Although it is not required for ADCP
processing, your editing plots will be fastly improved if you have
it. Follow the instructions in Section 9 or 10 to install
topography. You may have to fiddle with the default renderer
('zbuffer' or 'painters') to get topography to show up -- perhaps
different versions of matlab vary in how they treat patches?

We recommend using Postscript format (or Encapsulated Postscript) for
saving Matlab plots. Free Postscript interpreters and viewers are
readily available; again, Unix-like systems usually have them
installed by default, but for Windows you will need to download both
`Ghostscript and GSView <http://www.cs.wisc.edu/%7Eghost/>`_.

`Unzip and Zip <http://www.info-zip.org/>`_ from InfoZip.
These are excellent portable compression
and archiving utilities. We use them for our software
distribution. You probably already have either unzip or a Windows
equivalent; if not, you can download and install them. Linux
distributions may not install zip and unzip by default, but most
likely include them.

In the Future
--------------


Increasingly, we are using python with
`matplotlib <http://matplotlib.sourceforge.net/>`_
and `numpy/scipy <http://www.scipy.org/>`_
instead of Matlab for data analysis and plotting.

If you use python--and you should--then install the
`IPython <http://ipython.scipy.org/moin/>`_ shell.

`Mercurial <http://www.selenic.com/mercurial/>`_ is a
nice distributed version control system that we are now
using extensively. It is written in python. It is compact, easy to
install, easy to use, and fast. Much of our software is available
using mercurial, served on this web page:
http://currents.soest.hawaii.edu/hg
Follow `this link <hg_install.html>`_ to see how
we advocate installation.

SCons (http://www.scons.org/) is the new build system that we are
using for the core CODAS3 code, in place of makefiles.
Like Mercurial, SCons is written in python.

In the Past
-----------


Perl is an older scripting language that we have used extensively, but
no longer use for new work, and have almost completely phased out. It
is almost certainly installed on any Unix-like machine you might
use. For Windows, try Perl from ActiveState. Better yet, skip Perl and
go straight to Python.

For Windows Users
------------------

If you can, just switch to Linux. `Ubuntu <http://www.ubuntu.com/>`_
makes is easy.

`Cygwin from Cygnus (now RedHat) <http://www.cygwin.com/>`_ (Gnu port)
Unix-style tools and
environment for Windows, including a bash shell.

`MinGW and MSYS <http://www.mingw.org/>`_ are simpler alternatives to
Cygwin; we use a version of the MinGW
gcc compiler for compiling CODAS3 Windows binaries. See
`these instructions <compile_codas3.html>`_.

`Miktex <http://www.miktex.org/>`_ is an easy-to-install LaTeX
(and full TeX, MetaFont, Dvips,
etc) for Windows. Watch out for the A4 paper default in the dvips
configuration file (dvips/config/local/config.ps).