cbcunc/iris-on-mavericks.txt

## iris-on-mavericks.txt

Most of the IRIS installation can be accomplished with brew and pip. This is an install of the *minimum* Iris requirements. I'll work on extensions for Iris next. There are only a few and they are optional for things like Grib ingestion.

1) You will need to make sure that *both* XCode and the standalone XCode Command Line Tools are installed. Both are Homebrew dependencies.

2) brew install python
Brew's python includes pip and setuptools, which is sweet.

3) pip install virtualenv
You'll need to build Iris in a virtualenv as it depends on distutils packages which cannot be pip-uninstalled.

4) brew install gfortran
Not entirely necessary. Without it, you'll use gnu95 from XCode. But brew formulas are tested against gfortran. This may require setting the FC environment variable. My installs are compiled against gnu95 and they work, so I didn't set FC. Choice of Fortran compiler has an effect on scipy's performance. Conventional wisdom is that the proprietary Intel compiler is best. It may or not be something to investigate.

5)  brew tap homebrew/python
Brew hides a lot of python packages in a keg that needs tapping.

4) brew install numpy

5) brew install scipy

6) brew install freetype
Makes matplotlib nicer.

7) brew install matplotlib
If you have other Pythons installed on your system with numpy installed, you will need to add a PYTHONPATH to your bash profile.

8) brew install qt
If matplotlib is installed, it's a good idea to install iPython for debugging. A few dependencies for some of the more useful modes of running iPython need to be installed first.

9) brew install pyqt

10) brew install wxwidgets

11) brew install wxpython

12) brew install zmq

13) brew install pyzmq

14) brew install pygments

15) pip install six
Now we need some things that aren't included in brew to make the notebook feature of iPython work.

16) pip install pytz

17) pip install jinja2

18) pip install tornado

19) pip install ipython
Amazingly, iPython is not included in brew.

20) brew install udunits
Back to brew formulae for Iris

21) brew install netcdf --enable-fortran
This will add Fortran bindings. We'll get Python bindings later.

22) cd ~/Development
We need to install some packages now via distutils, so it would be a good idea to do that in a virtualenv. Go to some directory you'd like to use for a farm of virtualenvs.

23) virtualenv iris

24) cd iris

25) . bin/activate
Notice that your command had changed to let you know that you have an activated virtualenv. the bin directory of the virtualenv is now the first directory searched in your PATH.

26) Download the latest Pyke release from Sourceforge into your virtualenv.

27) python -m zipfile -e pyke-1.1.1.zip
Use Python's zipfile module as a script to extract Pyke

28) cd pyke-1.1.1

29) python setup.py build
I think it's a good idea to run build before install.

30) python setup.py install

31) cd ..
I also installed doctest-tools in order to run the Pyke test cases, but that's not really necessary. I'm including the steps next simply for documentation purposes.

32) Download doctest-tools from the link on Pypi.
The new pip won't download packages hosted externally outside Pypi because we're changing pip to be more secure, so --externally-managed is deprecated with prejudice.

33) python -m zipfile -e doctest-tools-1.0a3.zip

34) cd doctest-tools-1.0a3

35) python setup.py build

36) python setup.py install

37) cd ..
Back to the virtualenv

38) cd pyke-1.1.1

39) python ../testall.py
This will search Pyke for test cases and run them. Expect a few errors, but that's OK.

40) cd ..
Back to the virtualenv

41) pip install Cython
Cython is an unstated dependency for carotopy. We could update their documentation.

42) brew install gdal
Gdal (and its dependencies geos and proj which brew remembers) is an another unstated dependency for cartopy.

43) pip install shapely
Another unstated cartopy dependency.

44) pip install pyshp
Another unstated cartopy dependency.

45) Download the tar.gz, not the zip, of cartopy to the virtualenv.

46) tar -xzvf cartopy-0.10.0.tar.gz

47) cd cartopy-0.10.0

48) python setup.py build

49) python setup.py install

50) cd ..

51) Download biggus from the same Github organization (Scitools) that owns Iris. The Iris installation documentation needs a lot of updating. But it doesn't even mention its own product biggus, which is required by the development verion of Iris 1.7.

52) Don't use python's zipfile to extract biggus into the virtualenv. The zip file is broken (it contains an empty directory which is a zip file no-no). Just double click on it in Finder instead. The OSX extractor deals with broken zip files gracefully.

53) cd biggus-master

54) python setup.py build

55) python setup.py install

56) cd ..

57) pip install netCDF4
Finally get those Python bindings, even though they are already included as pure Python in scipy. I can't figure out why people don't default to the them if the C library isn't present. The C library is faster, though.

58) Download Iris from Github.
Iris is an unfortunate name. There is already a well known package called Iris on Pypi that is not the same things. The name of Iris will have to change if it is ever going to by pip-installable.

59) Don't use python's zipfile to extract Iris into the virtualenv. The zip file is broken, Just double click on it in Finder instead.

60) cd iris-master

61) python setup.py build

62) python setup.py install

63) cd ..
Iris is installed now. But we need to install the sample data to confirm Iris works. For some reason, Scitools keeps the sample data in a separate project on Github.

64) pushd

65) cd ../lib/python2.7/site-packages/Iris-1.7.0_dev-py2.7.egg/iris
We will install the sample data in the default place to look for it, which is in Iris' egg.

66) Download the sample data project from Scitools' Github.

67) Don't use python's zipfile to extract the sample into the package egg. The zip file is broken, Just double click on it in Finder instead.

68) ln -s iris-sample-data-master/sample_data sample_data
Don't pollute the egg with random files. Link the sample data instead.

69) popd
Now we're ready to run Iris:

70) python iris-master/doc/iris/example_code/graphics/COP_1d_plot.py

	Most of the IRIS installation can be accomplished with brew and pip. This is an install of the minimum Iris requirements. I'll work on extensions for Iris next. There are only a few and they are optional for things like Grib ingestion.

	1) You will need to make sure that both XCode and the standalone XCode Command Line Tools are installed. Both are Homebrew dependencies.

	2) brew install python
	Brew's python includes pip and setuptools, which is sweet.

	3) pip install virtualenv
	You'll need to build Iris in a virtualenv as it depends on distutils packages which cannot be pip-uninstalled.

	4) brew install gfortran
	Not entirely necessary. Without it, you'll use gnu95 from XCode. But brew formulas are tested against gfortran. This may require setting the FC environment variable. My installs are compiled against gnu95 and they work, so I didn't set FC. Choice of Fortran compiler has an effect on scipy's performance. Conventional wisdom is that the proprietary Intel compiler is best. It may or not be something to investigate.

	5) brew tap homebrew/python
	Brew hides a lot of python packages in a keg that needs tapping.

	4) brew install numpy

	5) brew install scipy

	6) brew install freetype
	Makes matplotlib nicer.

	7) brew install matplotlib
	If you have other Pythons installed on your system with numpy installed, you will need to add a PYTHONPATH to your bash profile.

	8) brew install qt
	If matplotlib is installed, it's a good idea to install iPython for debugging. A few dependencies for some of the more useful modes of running iPython need to be installed first.

	9) brew install pyqt

	10) brew install wxwidgets

	11) brew install wxpython

	12) brew install zmq

	13) brew install pyzmq

	14) brew install pygments

	15) pip install six
	Now we need some things that aren't included in brew to make the notebook feature of iPython work.

	16) pip install pytz

	17) pip install jinja2

	18) pip install tornado

	19) pip install ipython
	Amazingly, iPython is not included in brew.

	20) brew install udunits
	Back to brew formulae for Iris

	21) brew install netcdf --enable-fortran
	This will add Fortran bindings. We'll get Python bindings later.

	22) cd ~/Development
	We need to install some packages now via distutils, so it would be a good idea to do that in a virtualenv. Go to some directory you'd like to use for a farm of virtualenvs.

	23) virtualenv iris

	24) cd iris

	25) . bin/activate
	Notice that your command had changed to let you know that you have an activated virtualenv. the bin directory of the virtualenv is now the first directory searched in your PATH.

	26) Download the latest Pyke release from Sourceforge into your virtualenv.

	27) python -m zipfile -e pyke-1.1.1.zip
	Use Python's zipfile module as a script to extract Pyke

	28) cd pyke-1.1.1

	29) python setup.py build
	I think it's a good idea to run build before install.

	30) python setup.py install

	31) cd ..
	I also installed doctest-tools in order to run the Pyke test cases, but that's not really necessary. I'm including the steps next simply for documentation purposes.

	32) Download doctest-tools from the link on Pypi.
	The new pip won't download packages hosted externally outside Pypi because we're changing pip to be more secure, so --externally-managed is deprecated with prejudice.

	33) python -m zipfile -e doctest-tools-1.0a3.zip

	34) cd doctest-tools-1.0a3

	35) python setup.py build

	36) python setup.py install

	37) cd ..
	Back to the virtualenv

	38) cd pyke-1.1.1

	39) python ../testall.py
	This will search Pyke for test cases and run them. Expect a few errors, but that's OK.

	40) cd ..
	Back to the virtualenv

	41) pip install Cython
	Cython is an unstated dependency for carotopy. We could update their documentation.

	42) brew install gdal
	Gdal (and its dependencies geos and proj which brew remembers) is an another unstated dependency for cartopy.

	43) pip install shapely
	Another unstated cartopy dependency.

	44) pip install pyshp
	Another unstated cartopy dependency.

	45) Download the tar.gz, not the zip, of cartopy to the virtualenv.

	46) tar -xzvf cartopy-0.10.0.tar.gz

	47) cd cartopy-0.10.0

	48) python setup.py build

	49) python setup.py install

	50) cd ..

	51) Download biggus from the same Github organization (Scitools) that owns Iris. The Iris installation documentation needs a lot of updating. But it doesn't even mention its own product biggus, which is required by the development verion of Iris 1.7.

	52) Don't use python's zipfile to extract biggus into the virtualenv. The zip file is broken (it contains an empty directory which is a zip file no-no). Just double click on it in Finder instead. The OSX extractor deals with broken zip files gracefully.

	53) cd biggus-master

	54) python setup.py build

	55) python setup.py install

	56) cd ..

	57) pip install netCDF4
	Finally get those Python bindings, even though they are already included as pure Python in scipy. I can't figure out why people don't default to the them if the C library isn't present. The C library is faster, though.

	58) Download Iris from Github.
	Iris is an unfortunate name. There is already a well known package called Iris on Pypi that is not the same things. The name of Iris will have to change if it is ever going to by pip-installable.

	59) Don't use python's zipfile to extract Iris into the virtualenv. The zip file is broken, Just double click on it in Finder instead.

	60) cd iris-master

	61) python setup.py build

	62) python setup.py install

	63) cd ..
	Iris is installed now. But we need to install the sample data to confirm Iris works. For some reason, Scitools keeps the sample data in a separate project on Github.

	64) pushd

	65) cd ../lib/python2.7/site-packages/Iris-1.7.0_dev-py2.7.egg/iris
	We will install the sample data in the default place to look for it, which is in Iris' egg.

	66) Download the sample data project from Scitools' Github.

	67) Don't use python's zipfile to extract the sample into the package egg. The zip file is broken, Just double click on it in Finder instead.

	68) ln -s iris-sample-data-master/sample_data sample_data
	Don't pollute the egg with random files. Link the sample data instead.

	69) popd
	Now we're ready to run Iris:

	70) python iris-master/doc/iris/example_code/graphics/COP_1d_plot.py