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 Program 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. fftw (version 2.1.3+)   (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

       OR

       % ./configure --enable-shared=yes --enable-float
       
       Followed by:
       
       % make


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

        % ./configure
		% make

    3. Boost (version 1.32+)    (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 compilation.  Most UNIX systems will
       probably use the "gcc" toolset; visit 
       http://www.boost.org/more/getting_started.html#Tools for a
       complete listing.        

       % bjam "-sTOOLS=gcc" install 

       Header files from the Boost installation (located in the
       "boost" subdirectory of the Boost installation
       (eg. /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
      
  
    4. CMake (version 2.0.6+)    (http://www.cmake.org)
       Executables for several platforms are available; source code
       can also be used for custom installations.



 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)

    For development the following libraries/programs are required (see
    Appendix A for installation help):

    - Python (version 2.2+)             (http://www.python.org)
    
    - Boost Python (version 1.32+)		(http://www.boost.org)
    
    - numpy 	(http://www.scipy.org)



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  $EMAN2DIR/lib
          setenv PYTHONPATH .:$HOME/EMAN2/lib

	  for bash in .bashrc add:
	
          export EMAN2DIR=$HOME/EMAN2
          export PATH=$PATH:$EMAN2DIR/bin
          export 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(AMD64): 	ENABLE_OPTERON
        - Mac G5:  			ENABLE_G5
          
4.2  How to Generate Latest Documentation
-----------------------------------------

   1. Install doxygen (version 1.4.3+, http://www.doxygen.org)
   2. Install graphviz (http://www.graphviz.org/)
   3. install latex (http://www.latex-project.org/)
   4. After you have a successful EMAN2 install, i.e., you can import EMAN2 in Python,
      cd EMAN2/src/build
      ccmake ../eman2
      type 't' toggle to advanced mode, 
      check ENABLE_AUTODOC to ON
      make 
      make install   
    All documents will be in your EMAN2/doc directory.

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"
       3) Mac OS X:  % bjam “-sTOOLS=darwin”

    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

