Compiling EMAN2 on Mac OS X

It is recommended to install or build all dependency packages directly, instead of using a package manager such as Fink or MacPorts. We will also link against the Python environment included with Mac OS X.

For each dependency, a known working versions is listed in parentheses. Older versions may or may not work; newer versions (unless noted: iPython, png) are generally fine.

Some packages have known issues compiling on Mac OS X. Please see the Notes section at the bottom of the page if you encounter errors.

These instructions have been tested on Mac OS X 10.7 and 10.8, and should also work fine on 10.6.

Version Specific Notes

OSX - Mavericks (10.9)

A few notes when upgrading a working build platform on OSX 10.8 to 10.9:

Required Packages

Xcode (4.3)

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.

If you have upgraded your system from a previous version of Mac OS X and/or a previous version of Xcode, make sure previous versions have been "cleanly" removed.

sudo /Developer/Library/uninstall-devtools --mode=all

Installing Xcode is a two step process. First, install Xcode from the Mac App Store. Second, open Xcode, and go to "Preferences" then "Downloads". Select "Command Line Tools" and click the "Install" button to the right. Wait for this to complete.

Qt4 (4.8)

Qt is a graphics library for cross-platform user interfaces. I recommend using the binary installer for the Qt libraries here:

http://qt-project.org/downloads

You will want the "Qt libraries 4.8.3 for Mac" which includes a GUI-based installer inside the disk image.

Note: If there is an error that the installer cannot be opened because it is from an "unidentified developer", control-click on the installer package and select "Open" to override the system's security settings.

boost (1.51)

Boost is a set of useful, standardized libraries for C++. It is used to generate the Python-C++ interface in EMAN2.

http://sourceforge.net/projects/boost/files/boost/1.51.0/

boost_1_51_0.tar.gz

./bootstrap.sh --with-libraries=python,system,filesystem,thread
./bjam
sudo ./bjam install

gsl (1.15)

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

http://mirrors.kernel.org/gnu/gsl

gsl-1.15.tar.gz

./configure --disable-static --enable-shared
make
sudo make install

fftw3 (3.2)

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).

http://www.fftw.org/download.html

fftw-3.2.2.tar.gz

# This compiles the single precision library
./configure --enable-shared --enable-float
make
sudo make install

# This compiles the double precision library
./configure --enable-shared
make
sudo make install

Berkeley DB (5.3)

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.

http://www.oracle.com/technology/software/products/berkeley-db/index.html

Berkeley DB 5.3.21.NC.tar.gz

cd build_unix
../dist/configure
make
sudo make install

If using Mountain Lion and therefore Xcode 4.6, you'll need to patch DB up:

Go to the un-tarred source code directory you've downloaded, then into the subfolder src, and there into dbinc

cd db-5.3.21.NC/src/dbinc

Then download the patch, by typing the following in the command line

curl -O https://raw.github.com/narkoleptik/os-x-berkeleydb-patch/master/atomic.patch

Make the actual patch take effect

patch src/dbinc/atomic.h < atomic.patch

Now try building BerkeleyDB again

cd ../../build_unix
../dist/configure
make
sudo make install

Freetype (2.4)

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.

http://download.savannah.gnu.org/releases/freetype/

freetype-2.4.10.tar.gz

./configure --enable-shared
make
sudo make install

Important Note: There is an issue with the Freetype headers, resulting in errors about a missing "freetype/config/ftheader.h". To correct this, make the following link if you installed your own Freetype:

sudo ln -s /usr/local/include/freetype2/freetype /usr/local/include/freetype

If you are using the system's Freetype, make an analogous link in the SDK package, e.g.:

ln -s /Developer/SDKs/MacOSX10.7.sdk/usr/X11/include/freetype2/freetype /Developer/SDKs/MacOSX10.7.sdk/usr/X11/include/freetype

ftgl (2.1)

FTGL is a free, open source library to enable developers to use arbitrary fonts in their OpenGL applications.

http://sourceforge.net/projects/ftgl

ftgl-2.1.2.tar.gz

./configure --enable-shared
make
sudo make install

cmake (2.8)

CMake is a family of tools designed to build, test and package software. It is used to generate the Makefiles for compiling EMAN2.

http://www.cmake.org/cmake/resources/software.html

cmake-2.8.5.tar.gz

You may use the CMake binary installer package, or compile from source.

./configure
make
sudo make install

Required Packages (Python Modules)

sip (4.12)

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.

http://www.riverbankcomputing.co.uk/software/sip/download

sip-4.12.4.tar.gz

python configure.py
make
sudo make install

PyQt4 (4.8)

PyQt4 provides Python bindings for Qt4.

http://www.riverbankcomputing.co.uk/software/pyqt/download

PyQt-mac-gpl-4.8.5.tar.gz

If you have compiled from source:

python ./configure.py --confirm-license -e QtCore -e QtGui -e QtOpenGL
make
sudo make install

Note: If you receive an error about "unable to find qmake" or similar during configure, locate the qmake tool (e.g., /usr/bin/qmake-4.8, $HOME/QtSDK/Desktop/Qt/4.8.1/gcc/bin/qmake, etc) and provide the path using the "-q" option, e.g.:

python ./configure.py --confirm-license -e QtCore -e QtGui -e QtOpenGL -q $HOME/QtSDK/Desktop/Qt/4.8.1/gcc/bin/qmake

bsddb3 (5.3)

bsddb3 provides Python bindings for the Berkeley DB API.

http://pypi.python.org/pypi/bsddb3/

bsddb3-5.3.0.tar.gz

bsddb3 can be installed using easy_install ("sudo easy_install bsddb3"), or compiled and installed from the source distribution.

python setup.py build
sudo python setup.py install

Note: You may need need to provide the path to where Berkeley DB is installed, using the --berkeley-db option:

python setup.py build --berkeley-db=/usr/local/BerkeleyDB.5.3

PyOpenGL (3.0)

PyOpenGL provides Python bindings for OpenGL.

http://pyopengl.sourceforge.net

PyOpenGL-3.0.1.tar.gz

PyOpenGL can be installed using easy_install ("sudo easy_install PyOpenGL"), or installed from the source distribution.

python setup.py build
sudo python setup.py install

iPython (0.10)

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.

Please note that iPython versions NEWER than 0.10 are currently NOT supported. The developers refactored parts of the API without providing any backwards compatibilty. We are currently updating EMAN2 to use the new API, at which point I will remove this warning. In the interim, please use iPython version 0.10. With easy_install:

easy_install ipython==0.10

or alternatively you can download it yourself:

http://archive.ipython.org/release/0.10.2

ipython-0.10.2.tar.gz

python setup.py build
sudo python setup.py install

matplotlib (1.1)

Matplotlib is a python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments.

http://matplotlib.sourceforge.net

matplotlib-1.1.1.tar.gz

Note: Earlier versions of matplotlib have known difficulties compiling easily on Mac OS X; use 1.1 or higher.

Note: If you want PNG image format support, make sure to install libpng as described below first.

Otherwise, matplotlib installs the same way as other distutils-based packages:

python setup.py build
sudo python setup.py install

png (1.2)

The PNG (Portal Network Graphics) format provides lossless-compressed image support. Mac OS X 10.7 Lion ships with libpng 1.5, in which some deprecated features in the PNG API were removed. EMAN2 is being updated to use these new methods. For now, use libpng 1.2 if you are compiling on 10.7.

http://sourceforge.net/projects/libpng/files/libpng12/1.2.46/

libpng-1.2.46.tar.gz

./configure --enable-shared
make
sudo make install

hdf5 (1.8)

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.

http://www.hdfgroup.org/ftp/HDF5/current/src/

hdf5-1.8.5.tar.gz

./configure --enable-shared --prefix=/usr/local
make
sudo make install

Optional Dependencies

These packages are optional, and provide support for additional file formats (tiff, hdf5, png, jpeg). If you skip these packages, you will need to adjust your EMAN2 cmake configuration. I recommend installing all of them.

jpeg (8c)

Library for writing JPEG image files. JPEG used to be difficult to compile on OS X, but it has been improved recently and should compile without problems.

http://www.ijg.org/files

jpegsrc.v8c.tar.gz

./configure --enable-shared
make
sudo make install

Note: if you disable JPEG support in the cmake file you must also disable TIFF support.

tiff (3.8)

Library for reading and writing TIFF image files.

http://dl.maptools.org/dl/libtiff

tiff-3.8.2.tar.gz

./configure --enable-shared
make
sudo make install

Note: Curiously, HDF5 does not use /usr/local as the default installation prefix. Make sure to include the --prefix option above.

readline

Readline is a module that provides command-line editing in iPython. ie - it allows you to use up and down arrows to look at previous commands, and a variety of other useful functions. OSX ships with a readline module. However, this module is not the official readline module, but a mostly compatible one with more liberal licensing. The mostly is the problem, and this library causes all sorts of problems with command-line editing in ipython (not just for EMAN2)!

Installing the official readline module is trivial, just type in the command line:

easy_install readline 

However, what is less obvious is that you also need to disable the OSX provided readline, or it will be used in preference to the one you install. To do this under 10.7, for example: mv /System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload/readline.so /System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload/readline_disable.so

Configure EMAN2

EMAN2 is now hosted on GitHub. Here is a direct link to dowload the source. Just hit the "clone or download" button:

https://github.com/cryoem/eman2

Second, create a build directory for EMAN2. I generally keep the EMAN2 source CVS working directory in $HOME/src/eman2, and use $HOME/src/eman2build as my build directory.

Go to your build directory, and run ccmake with the EMAN2 source directory as the argument:

ccmake $HOME/src/eman2

Press "c" to do an initial configuration. If you have followed the instructions above, all of the library and include paths should automatically be set correctly. Review the options, including EMAN_INSTALL_PREFIX which is the installation directory. When done, press "c" again, then "g" to generate Makefiles.

The following is my configuration on Mac OS X 10.8:

 BOOST_INCLUDE_PATH               /usr/local/include                                                                                                                                                                     
 BOOST_LIBRARY                    /usr/local/lib/libboost_python.dylib                                                                                                                                                   
 CMAKE_OSX_ARCHITECTURES                                                                                                                                                                                                 
 CMAKE_OSX_SYSROOT                /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk                                                                                     
 CMAKE_VERBOSE_MAKEFILE           OFF                                                                                                                                                                                    
 EMAN_INSTALL_PREFIX              /Volumes/irees/EMAN2                                                                                                                                                                   

 ENABLE_ATHLON                    OFF                                                                                                                                                                                    
 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_FTGL                      ON                                                                                                                                                                                     
 ENABLE_HDF5                      ON                                                                                                                                                                                     
 ENABLE_HDFIOCACHE                OFF                                                                                                                                                                                    
 ENABLE_IOCACHE                   OFF                                                                                                                                                                                    
 ENABLE_JPEG                      ON                                                                                                                                                                                     
 ENABLE_LEOPARD                   OFF                                                                                                                                                                                    
 ENABLE_MEMDEBUG                  OFF                                                                                                                                                                                    
 ENABLE_MEMDEBUG2                 OFF                                                                                                                                                                                    
 ENABLE_MOUNTAIN_LION             ON                                                                                                                                                                                     
 ENABLE_NATIVE_FFT                OFF                                                                                                                                                                                    
 ENABLE_NFFT2                     OFF                                                                                                                                                                                    
 ENABLE_OPENGL                    ON                                                                                                                                                                                     
 ENABLE_OPTPP                     OFF                                                                                                                                                                                    
 ENABLE_PNG                       ON                                                                                                                                                                                     
 ENABLE_PROFILE                   OFF                                                                                                                                                                                    
 ENABLE_RT                        ON                                                                                                                                                                                     
 ENABLE_SPARX_CUDA                OFF                                                                                                                                                                                    
 ENABLE_TIFF                      ON                                                                                                                                                                                     
 ENABLE_V4L2                      OFF                                                                                                                                                                                    
 ENABLE_WINDOWS_VC                OFF                                                                                                                                                                                    
 ENABLE_X86_64                    ON                                                                                                                                                                                     

 FFTW3_INCLUDE_PATH               /usr/local/include                                                                                                                                                                     
 FFTW3_LIBRARY                    /usr/local/lib/libfftw3f.dylib                                                                                                                                                         
 FREETYPE_INCLUDE_PATH            /usr/local/include                                                                                                                                                                     
 FREETYPE_LIBRARY                 /usr/local/lib/libfreetype.dylib                                                                                                                                                       
 FTGL_INCLUDE_PATH                /usr/local/include                                                                                                                                                                     
 FTGL_LIBRARY                     /usr/local/lib/libftgl.dylib                                                                                                                                                           
 GLU_INCLUDE_PATH                 /usr/local                                                                                                                                                                             
 GLU_LIBRARY                      /System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGLU.dylib                                                                                                          
 GL_INCLUDE_PATH                  /usr/local                                                                                                                                                                             
 GL_LIBRARY                       /System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.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                /usr/local/include                                                                                                                                                                     
 JPEG_LIBRARY                     /usr/local/lib/libjpeg.dylib                                                                                                                                                           
 NUMPY_INCLUDE_PATH               /System/Library/Frameworks/Python.framework/Versions/2.7/Extras/lib/python/numpy/core/include                                                                                          
 PNG_INCLUDE_PATH                 /usr/local/include                                                                                                                                                                     
 PNG_LIBRARY                      /usr/local/lib/libpng.dylib                                                                                                                                                            
 PYTHON_INCLUDE_PATH              /System/Library/Frameworks/Python.framework/Headers                                                                                                                                    
 PYTHON_LIBRARY                   /usr/lib/libpython2.7.dylib                                                                                                                                                            
 TIFF_INCLUDE_PATH                /usr/local/include                                                                                                                                                                     
 TIFF_LIBRARY                     /usr/local/lib/libtiff.dylib  
 ZLIB_LIBRARY                     /usr/lib/libz.dylib                                                                                                                                                                                                 

Configurations for 10.6 and 10.7 will be basically equivalent, except for version-specific options like ENABLE_MOUNTAIN_LION, and the CMAKE_OSX_SYSROOT option:

For 10.6, it should be: /Developer/SDKs/MacOSX10.6.sdk

For 10.7, it will be either /Developer/SDKs/MacOSX10.7.sdk or /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk if you are using Xcode 4.3 or higher.

For convenience, some people like to link /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs to /Developer/SDKs for shorter, more manageable paths.

= Build EMAN2 =

Compile in the build directory and install:

make
make install

The default installation directory (EMAN2_INSTALL_PREFIX) is $HOME/EMAN2.

Configure Shell

If you are using the bash shell, add the following lines to your .bashrc file

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

Note: If you installed EMAN2 in someplace other than $HOME/EMAN2 (the EMAN_INSTALl_PREFIX in cmake above), place the correct path in this variable.

Then on the command line type bash or source ~/.bashrc. To test if EMAN2 is working properly, see if you can run e2.py. You should be greeted with some version information, then an ">>>" interactive interpreter prompt.

Unit Tests

EMAN2 includes a unit test suite. It will help verify that all components are working correctly.

cd $EMAN2DIR/test/rt
chmod +x *.py
python ./rt.py

Common Problems

General Issues

1. If you follow these instructions and get a segfault when running some of the GUI programs, you probably did not fully read the section on ccmake parameters. Pay special attention to the GL and GLU libraries

2. If you have EMAN2 binaries installed, move them out of the way BEFORE trying to build from source. Conflicts with library versions might arise otherwise.

3. If you have attempted to build EMAN2 from source before, SOME of the new builds for some dependencies WILL NOT REPLACE THE OLD LIBRARIES. You might want to DELETE or MOVE the OLD LIBRARIES in the /usr/local/lib/ directory. Alternatively, link to wherever the new .dylib files are generated.

Unsupported PowerPC

PowerPC is no longer actively maintained, and might not build. If you see this compilation error:

/usr/libexec/gcc/powerpc-apple-darwin10/4.2.1/as: assembler (/usr/bin/../libexec/gcc/darwin/ppc/as or /usr/bin/../local/libexec/gcc/darwin/ppc/as) for architecture ppc not installed
Installed assemblers are:
/usr/bin/../libexec/gcc/darwin/x86_64/as for architecture x86_64
/usr/bin/../libexec/gcc/darwin/i386/as for architecture i386
Modules/_bsddb.c:10059: fatal error: error writing to -: Broken pipe

You need set gcc's ARCHFLAGS before compilation:

export ARCHFLAGS="-arch i386 -arch x86_64"

Freetype Issues

If a package cannot find the Freetype header files, you will need to make a symlink to the correct locations. Please see the Freetype section in required dependencies.

Qt4 Issues

If the binary fails to install properly, try running the Qt uninstaller.

sudo /Developer/Tools/uninstall-qt.py 

If this doesn't work to remove Qt, try the following:

1. sudo QtSDK/SDKMaintenanceTool.app/Contents/MacOS/SDKMaintenanceTool
2. The tool’s dialog window will show up. in the dialog window select “Remove all components”, continue and uninstall the SDK.
3. By comparing the filesystem before and after the uninstall, this uninstallation only removed the QtSDK directory.
4. When reinstall, make sure to check the box “remove the old Qt Creator’s setting” in the installation interface.

PyQt4 Issues

_sipQtConnect

With some newer versions of PyQt4 (for example, 4.8), but earlier than 4.8.3, this error MIGHT occur:

'ImportError: dlopen(/Library/Python/2.6/site-packages/PyQt4/QtCore.so, 2): Symbol not found: _sipQtConnect'

The way to fix it requires to REMOVE your dysfunctional build of PyQt, untar the clean files again, and modify the configure.py file as follows: Look for these lines:

for a in sipcfg.arch.split():

And CHANGE the 'x86' in the third line for 'x86_64'. Then REBUILD. This appears to take care of the problem.

Broken Macro

Some people who have compiled Qt themselves have reported an error like this:

/usr/include/c++/4.2.1/bits/localefwd.h:58:34: error: macro "isspace" passed 2 arguments, but takes just 1

I haven't sorted out the cause of the problem, but one workaround that seemed to work was editing the offending C++ file (in our case, qpy/QtOpenGL/qpyopengl_attribute_array.cpp), and adding a #include <Python.h> directive as the first line, so the beginning of the file is:

#include <Python.h>
#include <QtGlobal>

RuntimeError unidentifiable C++ exception

Problem: When I try to run an eman2 python program I can get a RuntimeError unidentifiable C++ exception error

Solution: That probably means that the BOOST_LIBRARY in you ccmake file (see above) is set to /usr/local/lib/libboost_python.a and not /usr/local/lib/libboost_python-1_34_1.dylib. Change it, configure again (press c), then press g, then run a make install again. The problem should go away.

Running e2.py gives an ImportError complaining about libraries

For each of the dynamic libraries (*.dylib) in the EMAN2/lib directory make symbolic links to them in the same directory, but make it so the symbolic links have the .so extension (not the .dylib) extension To do this, type: sudo ln <source> <target> Where the source is EACH .dylib file, and the target is THE SAME FILE NAME, with .so ending replacing the .dylib

Linking CXX shared library ../lib/libEM2.dylib ld: cycle in dylib re-exports with /usr/X11R6/lib/libGL.dylib

Turn the ENABLE_LEOPARD flag ON in the ccmake file.

See http://developer.apple.com/qa/qa2007/qa1567.html for the details behind the issue.

What versions of everything did I use?

My most recent build, on October 1, 2012:

PyOpenGL-3.0.1.tar.gz           cmake-2.8.9.tar.gz              ftgl-2.1.3-rc5.tar.gz           jpegsrc.v8d.tar.gz              sip-4.14.tar.gz
PyQt-mac-gpl-4.9.5.tar.gz       db-5.3.21.NC.gz                 gsl-1.15.tar.gz                 libpng-1.2.50.tar.gz
boost_1_51_0.tar.gz             fftw-3.3.2.tar.gz               hdf5-1.8.9.tar.gz               matplotlib-1.1.1.tar.gz
bsddb3-5.3.0.tar.gz             freetype-2.4.10.tar.gz          ipython-0.10.2.tar.gz           qt-mac-opensource-4.8.3.dmg

EMAN2/COMPILE_EMAN2_MAC_OS_X_OLD (last edited 2017-02-08 15:39:57 by SteveLudtke)