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

Download and install Mercurial
---------------------------------

Mercurial is a distributed version control system.  We use it
to store and monitor changes in CODAS software.

Download and install `Mercurial <http://mercurial.selenic.com/>`_
(recommend "download and build from source" for unix, binary install
for Windows)

See bottom of page: `Mercurial: A Short Introduction`_


Getting CODAS programs
-------------------------

Make a directory in which all the subdirectories will live, for
example "adcp_programs".  All codas mercurial repositories (zip files,
if no repository exists) must land in this directory, and it is also
the directory in which you will run "hg clone" to make repositories in
section (2) , below.



(1) get the non-repository zip archives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These zip archives located  `here <../../zipped>`_.


**DOCUMENTATION**

+--------------------+-------------------+----------------------------------------------+
| zip archive name   | subdirectory      |  contents                                    |
+====================+===================+==============================================+
|adcp_doc.zip        |adcp_doc           |  same contents as on WWW                     |
+--------------------+-------------------+----------------------------------------------+

**PRACTICE DATASETS ("DEMOS")**

+--------------------+-------------------------+-----------------------------------------+
| zip archive name   | subdirectory            |  contents: adcp processing demos        |
+====================+=========================+=========================================+
|qdemo_pingdata.zip  |q_demos/oldpingdemo      |  original pingdata demo                 |
|                    |                         |                                         |
|                    |q_demos/newpingdemo      |  quick_adcp.py pingdata demo            |
+--------------------+-------------------------+-----------------------------------------+
|qdemo_vmdas.zip     |q_demos/vmdas_oslta      |  VmDAS (LTA)                            |
|                    |                         |                                         |
|                    |q_demos/vmdas_osbbenx    |  VmDAS (ENX)                            |
+--------------------+-------------------------+-----------------------------------------+
|qdemo_uhdas.zip     |q_demos/uhdas            |  UHDAS                                  |
+--------------------+-------------------------+-----------------------------------------+


(2) get the Mercurial repository CODAS software
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This method is fast and easy, especially for subsequent updates.


Change directories to your **adcp_programs** directory and
clone these **four** (4) repositores as follows:

::

 hg clone   http://currents.soest.hawaii.edu/hg/adcp_templates  adcp_templates
 hg clone   http://currents.soest.hawaii.edu/hg/codas3          codas3
 hg clone   http://currents.soest.hawaii.edu/hg/matlab          matlab
 hg clone   http://currents.soest.hawaii.edu/hg/pycurrents      pycurrents



A different method for installing CODAS programs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**deprecated**

This method uses the CODAS respositories at University of Hawaii
to create zip (or bz2 or tar) archives for installation on
one or more computers.  This would be a reasonable method to
be able to re-install the same version on more than one computer, or
computers not connected to the net.

The repository `web interface
<http://currents.soest.hawaii.edu/hg>`_ has buttons that
you can click to generate and download zip files based on the latest
code in the repository.  The advantage is that you do not need to
install Mercurial and you get only the code you need; the disadvantage
is that you don't get the history, and any subsequent update requires
wholesale replacement.


You will need to follow the process below for the following repositories:
 *  adcp_templates
 *  codas3
 *  matlab
 *  pycurrents


- Go to the UH Currents group website that contains the
  `UH ADCP Mercurial repositories <http://currents.soest.hawaii.edu/hg`

- click on the column that says "zip", "gz", or "bz2" for the directory
  you want.  A zip archive (or tar.gz file or tar.bz archive) will
  be created for the directory you are downloading.

- Save it to your disk.  The archive  (eg. zip archive) will have a funny
  name, for example "pycurrents.fffd209127a5.zip"

- unzip this directory in adcp_programs.  It will end up inside a subdirectory
  with the long name.  After extracting the archive, rename the long
  name to the generic short name, which in this example is
  "pycurrents".

- NOTE: If you download an on-the-fly archive this way, it is not a
  repository, and must be **replaced**; it cannot be upgraded in place.



Mercurial: A Short Introduction
--------------------------------

Here is a brief introduction to the  control that Mercurial gives you:


Use "hg  clone" to create the directories (the first time):

::

     cd adcp_programs
     hg clone  http://currents.soest.hawaii.edu/hg/pycurrents


Later, if you see that we have made changes and you want
to take advantage of them, or help us find the new bugs, use "hg pull -u"
to update a directory:

::

     cd adcp_programs/pycurrents
     hg pull -u


This will pull changes from the repository that you cloned;
if you need to pull from a different location, you can
specify that location on the command line. To see what the last 5 revisions were:

::

 hg log -l 5


To switch your working directory back to an earlier version, say 237:

::

 hg update -r 237


And then restore it to the latest:

::

  hg update -r tip

Or just see what the changes were from 237 to the latest:

::

 hg diff -r 237

See `the wiki <http://mercurial.selenic.com/wiki/>`_
for more information, and use the quick help, e.g.:

::

 hg help
 hg help pull
 hg help clone