Building EMAN2/SPARX/SPHIRE from Source

Standard instructions for establishing a build and runtime environment for EMAN/SPARX/SPHIRE on Linux and macOS

Contents

  1. Initial Setup (one time)
  2. Build and Install: Daily development, Update code, etc.
  3. Test install
    1. Troubleshooting
  4. Reporting Problems
  5. Linux Clusters

Initial Setup (one time)

  1. Remove/disable other Anaconda/Miniconda/EMAN installations. If you do not have Anaconda/Miniconda (or another copy of EMAN2/SPARX/SPHIRE) already installed in your account, skip to step 2. If you DO have Anaconda or Miniconda installed in your account, you must ensure that any existing install you have is not active in your shell (not in PATH, no LD_LIBRARY_PATH, PYTHONPATH or PYTHONHOME set). While it may also be possible to set up an environment for EMAN2 in your existing Anaconda install, you will need to know what you're doing, and adapt these instructions to your situation. 

       1 echo $PATH
   2 # make sure no Anaconda/Miniconda/EMAN2 entries
   3 echo $LD_LIBRARY_PATH
   4 echo $PYTHONPATH
   5 # ideally, both return nothing. If it set to something it is possible that it may interfere with Anaconda
   6 # strongly suggest at least during the install, ''unset'' both of these. After installation you can test
   7 # to see if they cause any issues
   8

  2. Download and install Miniconda: Linux or macOS 

       1 bash <Miniconda-installer>
   2 
   3 # There are a variety of options you can use, but the default command above is sufficient in most cases
   4 bash <Miniconda-installer> --help

    and follow the prompts. When you see Do you wish the installer to initialize Miniconda3 by running conda init?, say no, then move on to the next step.

  3. Initialize conda for shell interaction. These instructions will depend on what shell you use. The default on most systems is bash. If you use a different shell ( tsch, zsh, ... ), you will need to take this into account: 

       1 # for bash-like shells, such as bash and zsh
   2 source <miniconda-path>/etc/profile.d/conda.sh
   3 
   4 # for csh-like shells, such as csh and tcsh:
   5 source <miniconda-path>/etc/profile.d/conda.csh
   6 
   7 # <shell-name> is bash, fish, powershell, tcsh, xonsh or zsh
   8 conda init <shell-name>

    As it says after you run this command, you will need to close and reopen your shell/terminal for it to take effect. This command modified your shell initialization so the conda activate command can be used properly. For more information on conda-init and activation, see Environment Activation.

    macOS Users (bash only)

    On macOS, this modifies ~/.bash_profile. If you have a ~/.profile startup file, creation of ~/.bash_profile will prevent ~/.profile from being read. A simple solution is to source .profile within .bash_profile.

    For differences between login- and non-login shells and order of reading the startup files on macOS, see, https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/.

  4. Configure and update conda. 

       1 # We suggest the following, meaning you will need to use ''conda activate'' after logging in before using EMAN2
   2 conda config --set auto_activate_base False
   3 
   4 # Automatic conda updates may cause things to break, so we suggest making all package upgrades explicitly
   5 # The current version verified to work with EMAN is '''conda 4.9.1'''
   6 conda config --set auto_update_conda False
   7 
   8 # Flexible channel priority works better for eman-deps
   9 conda config --set channel_priority flexible
  10 
  11 # Update base environment to get the latest conda
  12 conda update --all -n base

  5. Create a new environment with EMAN2 dependencies. eman2 below is the name of the environment. You may make this whatever you like, as long as you remember to use the same name when doing conda activate. Note that this name will appear as part of your prompt when activated, so you may want to keep it short.

As of 9/20/2021 eman-deps version used for binaries on master branch is 29.0. This version has most dependencies pinned to current conda-forge pins. Notable upgrades include boost from 1.69 to 1.74 and OpenMPI from 3 to 4.

Note that the channel sources in the command have changed. conda-forge has higher priority than defaults now.

  • Command used before 9/20/2021, if needed: 

   1  conda create -n eman2 eman-deps=26 -c cryoem -c defaults -c conda-forge

Build and Install: Daily development, Update code, etc.

When you start a new shell, these are the steps you will need to take before running EMAN programs or compiling the system:

  1. Activate your environment. If you used a different name above, use it here too. 

       1 conda activate eman2

  2. Update and Checkout source code. Periodically you should update your source using standard git techniques. 

       1 cd <source-directory>    # <path-where-you-want-eman2-source>/eman2
   2 git fetch --all --prune  # optional cleanup of local files
   3 git checkout master      # to make sure you are building from the current master build rather than a branch someone is working on
   4 git pull                 # This is what actually updates your local copy of the code
   5

  3. CMake 

       1 cd <build-directory>
   2 # on Mac:
   3 cmake <source-directory>   # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE
   4 
   5 # on Linux:
   6 cmake <source-directory> -DENABLE_OPTIMIZE_MACHINE=ON  # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE
   7

    • cmake-gui

      • If you use cmake-gui, since conda is not in PATH anymore, cmake will fail to find the environment directory. In that case set CONDA_PREFIX to your conda environment directory manually.

      • Make sure to delete any cmake variables that cmake already found, variables like *_LIBRARY or similar, *_INCLUDE_PATH or similar, CONDA_EXECUTABLE, CMAKE_INSTALL_PREFIX and any variables that are expected to contain conda environment related values.
      • Configure and generate.

    • ccmake

      • If you use ccmake, you may get an error related to OpenGL. If this happens try quitting ccmake and running it again.

  4. Make 

       1 make -j 8
   2 make install

    Note that the make -j 8 above will compile using 8 threads. On some machines omitting the 8 will compile faster and cause no problems, and if you have more than 8 threads on your machine, you can increase the number.

Test install

Troubleshooting

Solutions to potential known problems will be listed here. If these don't help, please report your problem (http://groups.google.com/group/eman2):

Reporting Problems

Please, provide the output of the following commands when reporting a problem. Record the session via script command. This, also, records the commands. 

  1.    1 script filename.txt
   2 
   3 conda activate eman2
   4 
   5 conda info -a
   6 conda list
   7 conda list --explicit
   8 
   9 cd <source-dir>
  10 
  11 git status
  12 git log -1
  13 
  14 cd <build-dir>
  15 
  16 rm CMakeCache.txt
  17 cmake <source-dir>
  18 cmake . -LA
  19 
  20 make clean
  21 make -j
  22 make install
  23 make test-verbose
  24 
  25 conda deactivate
  26 
  27 exit # or Ctrl+D
  28

  2. Send filename.txt.

Linux Clusters

The approach above will install EMAN with a precompiled version of OpenMPI, which may or may not work with the batch queuing system on your cluster. If it does not work, the symptom will be that MPI parallel jobs will use only a single node, no matter how many you have allocated in your job. Currently, we do not have alternative OpenMPI installation instructions.