= Compiling EMAN2 on Mac OS X with Homebrew =

<<TableOfContents>>

Homebrew is a package management system for Mac. It is under active development and has strict policies to protect the user from damage via software. They also seek to protect users from themselves by avoiding sudo commands as much as possible. It is recommended that you do NOT install homebrew alongside other package managers such as macports/fink.

The following install was successful on OS X 10.8 (Mountain Lion) and OS X 10.10 (Yosemite) and 10.11 (El Capitan). If for any reason this doesn't work for you, I recommend refreshing your terminal (1st) and restarting your computer (2nd) since many of the packages downloaded might require sourcing. If neither solve your specific problem, please send an e-mail to a member of the lab and we'll try to address it as soon as possible. Also, it may be necessary to turn off SIP (System Integrity Protection) before proceeding when installing on El Capitan. To do this, reboot your machine while holding [CMD]+[R], open a terminal from the utilities menu at the top of the screen, type "csrutil disable", hit enter, type reboot, and hit enter to restart with SIP disabled.

Additionally, a known problem of using pure homebrew is that Qt windows seem to possess abnormally large buttons. A way around this is to install Qt/PyQt from source.

= Install homebrew =

To install homebrew, simply paste the following line into your favorite Mac terminal emulator:

{{{
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
}}}

To make sure everything is up to date, run:

{{{
brew update
}}}

To make sure everything is configured correctly, run the following command, addressing any warnings or errors before proceeding. Most of the warnings can be ignored, but for the smoothest install, it is better to address them sooner rather than later.

{{{
brew doctor
}}}

Additionally, add the following to your shell's 'rc' file to source homebrew programs ahead of the system's default versions:

{{{
export PATH=/usr/local/bin:$PATH
}}}

If you find you have already completed these instructions but are upgrading from OS X 10.8, 10.9, or 10.10, you will need to reinstall all homebrew packages or start from scratch. Luckily, there is an easy way to do the former:

{{{
brew list | xargs brew reinstall -v
}}}

This should reinstall all packages in their current versions.

= Required Packages =

== Xcode ==

Starting with Mac OS X 10.7 and Xcode 4.3, the developer tools are distributed through the Mac App Store instead of an installer package.

You'll also need the command line tools, which you can install with:

{{{
xcode-select --install
}}}

== CMake ==

CMake is a family of tools designed to build, test and package software. It is used to generate the Makefiles for compiling EMAN2. We install the homebrew version as follows:

{{{
brew install cmake
}}}

== Qt4 ==

Qt is a graphics library for cross-platform user interfaces. 

{{{
brew install qt --with-developer --with-docs --HEAD
}}}

== Boost ==

Boost is a set of useful, standardized libraries for C++. It is used to generate the Python-C++ interface in EMAN2. Homebrew comes with two 'boost' packages, and we'll need both to generate the libraries required for compiling EMAN2:

{{{
brew install boost --with-python
brew install boost-python
}}}

To install with MPI support, simply run the following commands instead:

{{{
brew install boost --with-mpi --with-python
brew install boost-python
}}}

== GSL ==

The GNU Scientific Library provides a wide range of mathematical routines such as random number generators, special functions and least-squares fitting.

{{{
brew install gsl
}}}

A personal concern is that there is no option to '--enable-float'; however, I have not run into any problems with this yet.

== FFTW3 ==

FFTW is a C subroutine library for computing the discrete Fourier transform (DFT) in one or more dimensions, of arbitrary input size, and of both real and complex data (as well as of even/odd data, i.e. the discrete cosine/sine transforms or DCT/DST). The most recent version is available from homebrew as follows:

{{{
brew install fftw
}}}

== Berkeley DB (5.3.28) ==

The Oracle Berkeley DB family of open source, embeddable databases provides developers with fast, reliable, local persistence with zero administration. EMAN2 uses Berkeley DB as a mechanism for local storage of project metadata.

Oracle has made their most recent version very VERY proprietary. To install BDB, you need an account on the following website at which you can download BDB 5.3.28.

http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index-082944.html

Once there, download "Berkeley_DB_5.3.28.tar.gz," then enter the following commands where you placed the download (preferably your source code directory).
{{{
tar -xzf db-5.3.28
cd db-5.3.28/build_unix
../../dist/configure
make
sudo make install
}}}

If you encounter errors during this process, I suggest trying the following:

{{{
cd db-5.3.28
cd src/dbinc
curl -O https://raw.githubusercontent.com/narkoleptik/os-x-berkeleydb-patch/master/atomic.patch
patch atomic.h < atomic.patch
cd ../../build_unix
../dist/configure
make
sudo make install
}}}

== Freetype and libPNG ==

On Mac OS X 10.8 and later, X11 and Freetype are no longer included by default. Even if you are using an earlier Mac OS X, I recommend installing your own Freetype. Homebrew offers the most recent version of freetype, but we'll need to explicitly include it in our configuration step later on.

{{{
brew install freetype
}}}


The PNG (Portal Network Graphics) format provides lossless-compressed image support. Although homebrew installs libpng as a dependency for freetype, it can be installed independently using the following command

{{{
brew install libpng
}}}


== FTGL ==

FTGL is a free, open source library to enable developers to use arbitrary fonts in their OpenGL applications. We can install it as follows:

{{{
brew install ftgl
}}}

== HDF5 ==

HDF5 is a data model, library, and file format for storing and managing data. It supports an unlimited variety of datatypes, and is designed for flexible and efficient I/O and for high volume and complex data.

{{{
brew tap homebrew/science
brew install hdf5
}}}

== SIP ==

Python's SIP (not to be confused with Mac OS X's SIP) is a tool that makes it very easy to create Python bindings for C and C++ libraries. It was originally developed to create PyQt, the Python bindings for the Qt toolkit, but can be used to create bindings for any C or C++ library.

{{{
brew install sip
}}}

== PyQt4 ==

PyQt4 provides Python bindings for Qt4. This software underlies every EMAN2 GUI application.

{{{
brew install pyqt
}}}

= Required Python Modules =

== PIP ==

Pip is a package manager for python. To install it, use the system's own "easy_install" program

{{{
easy_install pip
}}}

== Numpy ==

Numpy is an array manipulation package for python. To install, run

{{{
pip install numpy --upgrade
}}}

== bsddb3 ==

bsddb3 provides Python bindings for the Berkeley DB API.

Having previously defined the BERKELEYDB_DIR environment variable, we can install bsddb3 with pip very easily:

{{{
pip install bsddb3
}}}

== PyOpenGL ==

PyOpenGL provides Python bindings for OpenGL. There is a pip package for it, available here, along with an acceleration package for optimization of certain graphics routines.

{{{
pip install PyOpenGL PyOpenGL-accelerate
}}}

== IPython ==

IPython provides a rich toolkit to help you make the most out of using Python interactively. EMAN2 uses iPython for the "e2.py" interactive interpreter environment.

{{{
pip install ipython
}}}

== Matplotlib ==

Matplotlib is a python 2D and 3D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments. It can be installed with the following line:

{{{
pip install matplotlib
}}}

For examples and inspiration, see: [[http://matplotlib.org/gallery.html]]

== Readline ==

{{{
pip install gnureadline
}}}

= Optional (Recommended) Packages =

== Readline ==

Readline facilitates command history parsing in python.

{{{
brew install readline
}}}
 
== JPEG ==

Jpeg is a library for writing JPEG image files. 

{{{
brew install jpeg
}}}

== TIFF ==

Libtiff is a library for reading and writing TIFF image files.

{{{
brew install libtiff
}}}

== For EMAN2 Developers ==

If you spend a lot of time developing EMAN2, you will likely want these packages

{{{
brew install git cvs doxygen gnu-indent cscope
}}}

Excellent documentation for GIT is available at: [[https://www.atlassian.com/git/]]

= Cleaning up =

Cleaning things up and ensuring that everything has been installed properly, run:

{{{
brew linkapps
brew cleanup
brew doctor
}}}

Most warnings observed when running 'brew doctor' are harmless, especially if you don't use homebrew extensively. Unless problems arise later on, we recommend ignoring them.

= The QUICK version =

{{{
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew update && brew doctor
brew install qt --with-developer --with-docs --HEAD
brew install cmake boost boost-python ftgl freetype readline sip pyqt
brew tap homebrew/science && brew install hdf5 jpeg libtiff fftw gsl
brew install git cvs doxygen gnu-indent cscope
brew linkapps && brew cleanup && brew doctor
sudo easy_install pip
sudo -H pip install “ipython[all]” matplotlib spicy numpy gnureadline —upgrade
sudo -H pip install PyOpenGL PyOpenGL-accelerate --upgrade
}}}

Download Berkeley DB 5.3.28.tar.gz (instructions above)

{{{
tar -xf db-5.3.28
cd db-5.3.28
cd src/dbinc
curl -O https://raw.githubusercontent.com/narkoleptik/os-x-berkeleydb-patch/master/atomic.patch
patch atomic.h < atomic.patch
cd ../../build_unix
../dist/configure
make
sudo make install
sudo -H pip install bsddb3 --upgrade
}}}

= Get EMAN2 source code =

EMAN2 is now hosted on [[www.github.org|GitHub]]. Here is a direct link to dowload the source. Just hit the "clone or download" button:

[[https://github.com/cryoem/eman2]]

= Configure EMAN2 =

1. Go to 'build' and type

{{{
ccmake ../eman2
}}}

2. Link all libraries properly. 

When using Homebrew, this phase takes a little more care to get right. I suggest comparing your screen to the one I've pasted below (using OS X 10.8):

{{{
BOOST_INCLUDE_PATH               /usr/local/include
 BOOST_LIBRARY                    /usr/local/lib/libboost_python.dylib
 CMAKE_BUILD_TYPE
 CMAKE_OSX_ARCHITECTURES
 CMAKE_OSX_DEPLOYMENT_TARGET
 CMAKE_OSX_SYSROOT                /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platf
 CMAKE_VERBOSE_MAKEFILE           OFF
 EMAN_INSTALL_PREFIX              /Users/jmbell/EMAN2
 ENABLE_AUTODOC                   OFF
 ENABLE_BOUNDS_CHECKING           OFF
 ENABLE_DEBUG                     OFF
 ENABLE_EMAN_CUDA                 OFF
 ENABLE_FFTW2                     OFF
 ENABLE_FFTW3                     ON
 ENABLE_FFTW_PLAN_CACHING         ON
 ENABLE_FFT_CACHING               OFF
 ENABLE_FTGL                      ON
 ENABLE_HDF5                      ON
 ENABLE_IOCACHE                   OFF
 ENABLE_JPEG                      ON
 ENABLE_MEMDEBUG                  OFF
 ENABLE_MEMDEBUG2                 OFF
 ENABLE_NATIVE_FFT                OFF
 ENABLE_NFFT2                     OFF
 ENABLE_OPENGL                    ON
 ENABLE_OPTIMIZE_MACHINE          ON
 ENABLE_OPTIMIZE_MOUNTAIN_LION    OFF
 ENABLE_OPTIMIZE_WINDOWS_VC       OFF
 ENABLE_OPTIMIZE_X86_64           OFF
 ENABLE_OPTPP                     OFF
 ENABLE_PNG                       ON
 ENABLE_PROFILE                   OFF
 ENABLE_RT                        ON
 ENABLE_SPARX_CUDA                OFF
 ENABLE_TIFF                      ON
 ENABLE_V4L2                      OFF
 FFTW3_INCLUDE_PATH               /usr/local/include
 FFTW3_LIBRARY                    /usr/local/lib/libfftw3f.dylib
 FREETYPE_INCLUDE_PATH            /usr/local/include/freetype2
 FREETYPE_LIBRARY                 /usr/local/lib/libfreetype.dylib
 FTGL_INCLUDE_PATH                /usr/local/include
 FTGL_LIBRARY                     /usr/local/lib/libftgl.dylib
 GSL_CBLAS_INCLUDE_PATH           /usr/local/include
 GSL_CBLAS_LIBRARY                /usr/local/lib/libgslcblas.dylib
 GSL_INCLUDE_PATH                 /usr/local/include
 GSL_LIBRARY                      /usr/local/lib/libgsl.dylib
 HDF5_INCLUDE_PATH                /usr/local/include
 HDF5_LIBRARY                     /usr/local/lib/libhdf5.dylib
 JPEG_INCLUDE_PATH                /Library/Frameworks/UnixImageIO.framework/Headers
 JPEG_LIBRARY                     /usr/local/lib/libjpeg.dylib
 NUMPY_INCLUDE_PATH               /System/Library/Frameworks/Python.framework/Versions/2.7/Extras/l
 PNG_INCLUDE_PATH                 /Library/Frameworks/UnixImageIO.framework/Headers
 PNG_LIBRARY                      /usr/local/lib/libpng.dylib
 PYTHON_INCLUDE_PATH              /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platf
 PYTHON_LIBRARY                   /usr/lib/libpython2.7.dylib
 TIFF_INCLUDE_PATH                /Library/Frameworks/UnixImageIO.framework/Headers
 TIFF_LIBRARY                     /usr/local/lib/libtiff.dylib
 ZLIB_LIBRARY                     /usr/lib/libz.dylib
}}}

= Build EMAN2 =

Once you're happy with the links, press 'c' to configure and then 'g' to generate the makefile. 

8. Still inside build type:

{{{
make -j16 && make install
}}}

9. Add the EMAN2 folder (and the examples folder therein) to your PATH via the .bashrc file

{{{
export EMAN2DIR=${HOME}/username/EMAN2                                                      
export PATH=$EMAN2DIR/bin:$PATH                                                             
export PATH=$EMAN2DIR/examples:$PATH                                                        
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$EMAN2DIR/lib                                       
export PYTHONPATH=$PYTHONPATH:$EMAN2DIR/lib:$EMAN2DIR/bin                                              
}}}

Once you refresh your shell by calling the shell in the terminal or by restarting your computer, everything should work properly. If the building process goes through without errors, the basic tests to see whether EMAN2 is actually installed properly, are 

10. A. Run e2speedtest.py from the command line

10. B. Run e2.py from the command line

10. C. Run e2display.py from the command line (assuming you're not on a cluster)

If everything went well, the above should run without failure and you can begin using EMAN2. If not, please double check that you've followed all instructions. If you have, feel free to post to the EMAN2 google group for assistance.