INSTALL.txt

=======
Install
=======

::

    pip install numpy && pip install .

It is of note that numpy must be installed before the rest of the packages.
Some required packages will not install concurrently with numpy. This is the
basic installation. If you need to perform any kind of operation on netCDF,
KML, etc you will need to install with extras. Please see Deploying.

Dependencies
============

Dependencies are listed in setup.py. Don't worry about them. Read this first to
find out whether you need all of them.

Dependency tree
---------------

All nodes are python packages except those marked as libraries.

* libcchdo
  - geoalchemy

    + SQLAlchemy
    + MySQL-python (optional if you have downloaded a cached database)

      * MySQL (library)

  - netCDF4 (optional) for netCDF file manipulation

    + numpy
    + netCDF >=3.0 (library)

      * HDF5 (library, needed to write netCDF 4 files)

  - cdecimal (optional but highly recommended) provides a HUGE speed boost
  - coverage (optional) only needed for test coverage
  - lxml (optional) used to generate HTML for csv_view

    + lxml (library)

  - docutils (optional) used to check ReStructuredText format.
  - oauth2 (optional) used for downloading Bitbucket wiki content
  - paramiko (optional) used for data directory manipulation
  - scipy (optional) needed for interpolation and scientific math
  - PIL (optional) needed for image processing plot thumbnails
  - matplotlib (optional) needed for plotting

    + geos (library)

  - basemap (optional) needed for plotting maps
  - pykml (optional) used to write KML documents.

External Libraries
------------------

You need to install these yourself based on your operating system.

* MySQL
* netCDF4

  - HDF5 - library needed by netCDF 4 to write files

* libgeos

Using pip
=========

You'll want to install pip (package manager for Python).

Developing
----------

When developing, you want to be able to edit and run code without reinstalling.
`pip` will allow you to do this by installing the package as editable::

    pip install --editable .

or

::

    pip install -e .

Again, if you wish to use any special functions, please see Deploying.

Deploying
---------

If you do not want any optional packages you can simply run pip install::

    pip install .

If you do want extras, you can find them under `extras_require`. Only 
`pip>=1.2.0` understands this command.

::

    # Install all extras
    pip install .[all]

    # Install only extras that are specified
    pip install .[speed,netcdf,plot,merge]

    # Install extras with code in editable mode
    pip install -e .[all]

Managed deployment
------------------

The included script libcchdo/scripts/hydro-vm is able to manage simultaneous
deployment of multiple versions of libcchdo. Follow these steps to install
hydro-vm properly

::

    # Install the script
    $ SCRIPT_NAME="hydro-vm"
    $ cp libcchdo/scripts/${SCRIPT_NAME} "${CCHDO_BINS}"
    $ sudo chown admin "${CCHDO_BINS}/${SCRIPT_NAME}"
    $ sudo chmod 755 "${CCHDO_BINS}/${SCRIPT_NAME}"

    # Add the script to the path
    $ CCHDO_BINS="/usr/local/cchdo/bin"
    $ echo "${CCHDO_BINS}" >> /etc/paths.d/cchdo

    # Automatically upgrade the main installation to the latest on git master
    $ alias as="sudo -u"
    $ as admin hydro-vm install

    # Install specific git commits as deployment_name
    # as admin hydro-vm install <commit> <deployment_name>