All aboard the Open Climate Workbench train... lets begin

Introduction

The following guide will help you setup the recommended working environment for OCW power users.

This guide will focus on setup for OS X with Developer Tools already installed and it assumes you are familiar using a terminal.

Dependency Installation

Install Homebrew

Homebrew is a package manager for OS X. It isn't completely necessary for this installation, however it will make it easier.

The project's website provides great documentation and installation is as easy as copying a single command into the terminal and following a few instructions.

Install Anaconda

Install the Anaconda Scientific Python Distribution from Continuum Analytics.

The installation is very simple and the Continuum Analytics site should have all the information you need to get started.

Install Pip

More than likely you already have pip installed but let's check anyway. Open a terminal and run:

> pip
Usage: pip COMMAND [OPTIONS]
You must give a command (use "pip help" to see a list of commands) 

 Install VirtualEnv and VirtualEnvWrapper

virtualenv is a tool for creating isolated Python environments and virtualenvwrapper makes using virtualenv super easy. You can install both by running the following commands:

> pip install virtualenv
> pip install virtualenvwrapper

Now that we have this installed we need to create an environment into which we will install our dependencies.

We will create an environment called ocw that you should work on whenever you want to run the toolkit. This makes sure that we don't clobber anything important on your system and keeps everything nicely separated.

> mkvirtualenv ocw

When you are done using OCW you should run deactivate to deactivate the virtual environment. Later, if you want to use OCW you should run workon ocw to activate the virtual environment. Make sure you have it activated before you continue with the following steps!

Install GEOS and Basemap

basemap is a extension to the popular Python plotting library matplotlib that helps plot data on maps. It requires the installation of the GEOS library to function. 

If you installed Homebrew as recommended above you can install GEOS with:

> brew install geos

Otherwise, you should go to the basemap project's website and following the instructions for installing only GEOS. Assuming you have downloaded the package and untar'ed it, you can easily install GEOS from the package folder with:

> cd geos-<version numbers here>
> ./configure --prefix=/usr/local
> make; make install

Next we need to set GEOS_DIR before installing basemap. If you installed GEOS manually you should set GEOS_DIR to whatever you placed in the --prefix flag passed to the configure command above. If you installed it with Homebrew then you can run the following to get package information and set GEOS_DIR:

> brew info geos
geos: stable 3.4.2
http://trac.osgeo.org/geos
/usr/local/Cellar/geos/3.4.2 (385 files, 8.2M) *
  Built from source
From: https://github.com//homebrew/commits/master/Library/Formula/geos.rb
==> Options
--c++11
	Build using C++11 mode
--universal
	Build a universal binary
> export GEOS_DIR=/usr/local/Cellar/geos/3.4.2

Install Additional Dependencies

There are a few more dependencies that you should install with pip. They're not all entirely necessary (Some are!), but you should probably install the anyway 

> pip install requests
# This is required for proper functionality
> pip install bottle
# Bottle needs to be installed for running the evaluation UI
> pip install sphinxcontrib-httpdomain
# If you want to build the project documentation you will need this package
> pip install WebTest
# A number of unit tests rely on this package
 

Get the Code

There are a few possible ways to get the code.

Get the latest release

Grab the latest release from OCW website. However, you should be aware that a number of the early releases are very unstable. It is recommended that you use one of the other two options instead as it is easier for the development team to help you address any problems you may have. That being said, if you know what you're doing go for it!

Grab the latest code from the ASF

If you're a user and you don't plan on contributing code back to the project you should pull the code from the primary project's git repository. You can download it into ~/climate with:

> cd
> git clone http://git-wip-us.apache.org/repos/asf/climate.git

Prepare a dev environment

If you plan to help out the project and send in a patch (Thanks by the way!) then you should fork the project on Github. After doing that you can clone the code into ~/climate with:

> cd
> git clone https://github.com/<your Github username>/climate.git

Make Everything Easier

The last thing we're going to do is make our ocw virtual environment a bit more helpful. Edit ~/.virtualenvs/postactivate in your favorite editor and add the following:

if [ $VIRTUAL_ENV == "$HOME/.virtualenvs/ocw" ] 
then
    # You want this to point to where ever you installed Anaconda. By default, this should work.
	PATH="$HOME/anaconda/bin":$PATH
    # This makes sure OCW is loaded properly when running python. Unfortunately the toolkit is 
    # not installable at the moment so this step is necessary for the time.
	export PYTHONPATH="$HOME/climate/:$HOME/climate/ocw/:$HOME/climate/rcmet/src/main/python/rcmes"
fi

This makes sure that whenever you are using the ocw virtual environment that the Anaconda Python is used (where all the awesome dependencies are installed!) and that your PYTHONPATH is set properly so the toolkit is loaded whenever you use Python. Don't worry though, when you deactivate the virtual environment your original variable values will be reset, so none of this will clobber your other work!