EMAN 2
------

Table of Contents:
Sec. 1     Required Libraries / Programs
Sec. 2     Optional Libraries / Programs
Sec. 3     Quick Installation
Sec. 4     Advanced Installation
Sec. 5     Notes for Developers
App. A     Help for Optional Progam Installation



1. Required libraries / Programs
--------------------------------

The following libraries are required for EMAN2 installation (the
libraries should be installed as shared-object libraries where applicable):

    1. fftw2 (version 2.1.3+) or fftw3  (http://www.fftw.org/) 
       To install fftw from source use either configure option:
       % ./configure --enable-static=no --enable-shared=yes --enable-float --enable-type-prefix
       % make


    2. gsl (version 1.6+)    (http://www.gnu.org/software/gsl/)

        % ./configure
		% make

	3. Python (version 2.3+)             (http://www.python.org)
	
	4. numpy 
                                        (http://www.scipy.org)
	
    5. Boost Python (version 1.32 or upper)    (http://www.boost.org) 

       3.1  Installing Boost requires Boost.Jam.  Executables and
	    source code for jam can be found at the Boost website.

       Installing Boost requires the user to identify a particular
       toolset to use during compliation.  Most UNIX systems will
       probably use the "gcc" toolset; visit 
       http://www.boost.org/more/getting_started.html#Tools for a
       complete listing. go to boost/libs/python/build:        

       % bjam "-sTOOLS=gcc" install 

       Header files from the Boost installation (located in the
       "boost" subdirectory of the Boost installation
       (ex. /boost_1_32_0/boost)) must now either be added to the
       compilers path or copied into an existing location on the path
       in a subdirectory /boost.

       One possibility for this might be:
       % cp -r boost /usr/include/boost
      
  
    6. CMake (version 2.0.5+)    (http://www.cmake.org)
       Executables for several platforms are available; source code
       can also be used for custom installations.

    7. PyQT4 - Involves several subpackages:
	* Qt 4.1+
	http://www.trolltech.com/developer/downloads/qt/x11

	Suggest:
	./configure -no-xrender 

	* SIP
	http://www.riverbankcomputing.co.uk/sip/download.php

	* PyQt4
	http://www.riverbankcomputing.co.uk/pyqt/download.php

	* PyOpenGL
	http://sourceforge.net/project/showfiles.php?group_id=5988

	8. IPython (version 0.7.3)	(http://ipython.scipy.org/moin/)


2.  Optional Libraries / Programs
----------------------------------        
    - To read/write HDF5 image, use hdf5 (http://hdf.ncsa.uiuc.edu/HDF5).
	  
    - To read TIFF image, use libtiff (http://www.libtiff.org)

    - To read PNG image, use PNG (http://www.libpng.org)

	- To create code based auto-generated documentation, see section 4.2.
	
3. Quick Installation 
----------------------

    Suppose you have source code eman2.tar.gz

       1) % cd $HOME
          % mkdir -p EMAN2/src
          % cd EMAN2/src
          % gunzip eman2.tar.gz
          % tar xf eman2.tar
      
       2) % mkdir build
          % cd build

       3) % cmake ../eman2
          % make
          % make install
      
       4) set up login shell
          for csh/tcsh, put the following to your .cshrc or .tcshrc file:
          
          setenv EMAN2DIR ${HOME}/EMAN2
          setenv PATH ${EMAN2DIR}/bin:${PATH}
          setenv LD_LIBRARY_PATH  ${LD_LIBRARY_PATH}:${EMAN2DIR}/lib
          setenv PYTHONPATH .:${HOME}/EMAN2/lib:${PYTHONPATH}

	  	  for bash in .bashrc add:
	
          export EMAN2DIR=${HOME}/EMAN2
          export PATH=${PATH}:${EMAN2DIR}/bin
          export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${EMAN2DIR}/lib
          export PYTHONPATH=${PYTHONPATH}:${HOME}/EMAN2/lib


		  
4. Advanced Installation
------------------------

   If your libraries (fftw, gsl, hdf, etc) are not found by Quick
   Installation, or if you want to change the compilation options,
   the following steps help:

       1) follow the first 2 steps in Quick Installation.
       
       2) If your libraries are not installed at the default places,
          set up the related environment variables:
            - fftw -> FFTWDIR
            - gsl  -> GSLDIR
            - tiff -> TIFFDIR
            - png  -> PNGDIR
            - hdf5 -> HDF5DIR
            - python -> PYTHON_ROOT and PYTHON_VERSION
            
       3) % ccmake ../eman2
          - type 'c' if it asks about "CMAKE_BACKWARDS_COMPATIBILITY".
          - make necessary changes for compilation flags.
	    - developers will probably want to set BOOST-LIBRARY to a
              Boost.Python object file (ex. libboost_python-gcc-1_32.so)
          - Then type 'c', and type 'g'.

       4) % make
          % make install          
                
4.1  Platform Dependent Optimization 
------------------------------------

    In CMake Configuration, enable the following option for your platform:
        - Athlon:  ENABLE_ATHLON
        - Opteron(Athlon 64): ENABLE_OPTERON
        - Mac G5:  ENABLE_G5
          
4.2  How to Generate Latest Documentation
-----------------------------------------
	
	in EMAN2/doc directory, except some hand-coded html and text files, 
	we have three groups of auto-generated documents:
	1. Latex documents generated from tex files, same content can be viewed
		in four formats: dvi, ps, pdf and html.
	2. Doxygen html files. 
	3. two html files describe processor and processor group.
	
	To create these files in EMAN2 building process, you need:  
   	1. Install doxygen (version 1.4.3+, http://www.doxygen.org)
   	2. Install latex2html (http://www.latex2html.org/)
   	3. Install Graphviz(dot) (http://www.graphviz.org/)
   	4. compile and install EMAN2 with "ENABLE_AUTODOC" set to off 
   	5. Choose "ENABLE_AUTODOC" in the CMake configuration, compile and install EMAN2 again
    

5. Notes For Developers
-----------------------

    0. For Emacs users, please add the following line to your $HOME/.emacs:
       (setq default-tab-width 4)

    1. Ensure the Boost.Python
           
    2. To generate new boost python wrapper, run
        % cd eman2/libpyEM
        % ./create_boost_python

    3. Windows Installer
       EMAN uses "Nullsoft Scriptable Install System" (http://nsis.sourceforge.net/)
       to generate the windows installer.
       It also uses "HM NIS Edit" (http://hmne.sourceforge.net/) as the editor.

       

Appendix A.
-----------

A.1. How to Install Boost Python
--------------------------------
   
    0. Download 'bjam' for your platform.
    
    1. Download boost source from http://www.boost.org. Assume the
       version is boost_1_32_0.
       % cd /usr/local/src; tar zxf boost_1_32_0.tar.gz; cd boost_1_32_0.
    
    2. Set up environment variables "PYTHON_ROOT" and "PYTHON_VERSION".
       For example, if your python is at /usr/bin/python then PYTHON_ROOT is
       "/usr". If your python version is 2.2.X, PYTHON_VERSION is '2.2'.
    
       a) check your shell: % echo $SHELL
       
       b) if you are using bash/zsh, do
          % export PYTHON_VERSION=2.2
          % export PYTHON_ROOT=/usr

          if you are using csh/tcsh, do
          % setenv PYTHON_VERSION 2.2
          % setenv PYTHON_ROOT /usr

    3. cd libs/python/build  [didn't do this]
    
    4. run 'bjam' with your options:
       1) linux-x86: % bjam
       2) SGI Irix:  % bjam "-sTOOLS=mipspro"

    5. login as root
    
    6. cp -df bin-stage/libboost_python.so* /usr/local/lib
       cd ../../..; cp -rf boost /usr/local/include


A.2. How to use your own python version
---------------------------------------

    If the python you want to use in your computer is not found by CMake,
    you may set up environment variables "PYTHON_ROOT" and "PYTHON_VERSION".
    For example, if your python is at /usr/local/python2.4/bin/python.
    PYTHON_ROOT is "/usr/local/python2.4". if your python is 2.4.X,
    PYTHON_VERSION is '2.4'.

       
A.3. How to Install numpy
----------------------------------
 
    From the website http://sourceforge.net/projects/numpy download source package.
 
    For windows, run the binary installer and the installation is
    complete.  Other users must download the source code and install
    manually as follows:

    - get source code numpy-1.0.1.tar.gz
    - % gunzip numpy-1.0.1.tar.gz
      % tar xf numpy-1.0.1.tar
    - login as root
    - % cd numpy-1.0.1; 
      % python setup.py install

	
