## page was renamed from EMAN2/COMPILE_EMAN2_MAC_OS_X = 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: * After upgrading XCode, you will need to launch it once as a GUI program to accept the agreement before the command-line tools will work * There were a few minor formal C++ errors that changed from warnings to errors. These were fixed in CVS, but if you have an older version of the source you may encounter them. * Boost had to be recompiled * Since this is a new Python, any python packages will need reinstalling * redo 'easy_install bsddb3' * redo 'easy_install pyopengl' * reinstall PyQt/sip (I also had to reinstall the Qt library package) * It is probably a good idea to re-run ccmake from scratch: * mv CMakeCache.txt CMakeCache.txt.old * rerun ccmake * if you have troubles with the recompile, you can do a 'diff CMakeCache.txt CMakeCache.txt.old' and compare the two to look for issues. = 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 [[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]] 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(): if a == 'i386': qmake_archs.append('x86') elif a == 'x86_64': qmake_archs.append('x86_64') elif a == 'ppc': qmake_archs.append('ppc') 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 directive as the first line, so the beginning of the file is: {{{ #include #include }}} == 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 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 }}}