Differences between revisions 93 and 119 (spanning 26 versions)
Revision 93 as of 2020-12-24 15:22:29
Size: 16581
Editor: SteveLudtke
Comment:
Revision 119 as of 2021-09-20 22:25:53
Size: 13584
Editor: TunayDurmaz
Comment: eman-deps 29
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from EMAN2/COMPILE_EMAN2_ANACONDA/2.9
Line 3: Line 4:
## <<TableOfContents()>>

{{{#!wiki note
Instructions from before the change to Anaconda are [[EMAN2/COMPILE_EMAN2_ANACONDA-PRE-CONDA-ENVIRONMENTS|here]], but they likely will not work with current versions of the source.
}}}

'''''WARNING: As of December, 2020 we are finally approaching the first Python 3 release. The "master" branch of EMAN2/SPHIRE/SPARX should have relatively few bugs at this point. You may install both the last stable release from Fall, 2019 and the current Python 3 build simultaneously. If you follow the instructions below through step 10, you should have a fully functional Python 3 build.
'''''

= Building EMAN2/SPARX/SPHIRE from Source =

''The EMAN2 source lives on [[https://github.com/cryoem/eman2|GitHub]], downloading the source is part of the instructions below. '''Do not download it yet!''' ''

These are the standard instructions for establishing a build and runtime environment for EMAN2/SPARX/SPHIRE on Linux and Mac. While the instructions look long, in reality it should only take 10-15 minutes to complete the entire process (with a decent network connection). This build uses [[https://www.anaconda.com/distribution/|Anaconda/Miniconda]] (DO NOT DOWNLOAD THE MOST RECENT VERSION FROM THIS LINK) for a working environment and most of the dependencies. Anaconda has become ubiquitous for Python and R-based scientific computing and education over the last decade. While it may be possible to build the system without using Anaconda, we do not recommend doing this, and cannot provide support for a non-Anaconda approach. If you follow the instructions below, you should have a painless source build very quickly.

Building on Windows is so complicated that we cannot provide generic instructions at this point in time.

Note that even with a source build it may be difficult to get this working on systems with very old operating system installs. We normally try to support OS versions as much as 5-7 years old. Please report any problems.

=== GPU Support (Linux Only!) ===

For features which support the GPU, please complete the standard source install instructions below, then follow the [[EMAN2/Install/BinaryInstallAnaconda/2.31#Using_the_GPU|GPU instructions]] from the binary installation page.

== Building and Installing EMAN2/SPHIRE/SPARX ==

Anaconda comes in two flavors ''Anaconda'' which is a full featured system with many libraries and capabilities built in, and ''Miniconda'' which is a stripped down version of the system. Both systems are the same, it is just a question of which packages come preinstalled. These instructions are based on the smaller Miniconda install. You may also have success with Anaconda, but a better approach may be to install Miniconda, then add in any extra packages you actually need.

We make use of the [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html|environment]] system in Anaconda to isolate EMAN2 dependencies from other Anaconda packages you may have installed. If you need to install other packages you wish to use in concert with EMAN2, you will need to install them within the EMAN2 environment. Be warned that sometimes installing another package may trigger a version change in one of EMAN2's dependencies, which may or may not be a problem, depending on which dependency it is. We strongly suggest getting the base EMAN2 installed and working first, before trying to install any additional packages within the same Anaconda environment.

=== Initial Setup and Build (one time) ===

 1. '''Remove/deactivate other Anaconda installs.''' 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 or PYTHONPATH 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.


{{{#!html
<h1 style="margin-bottom:5px;"> Building EMAN2/SPARX/SPHIRE from Source </h1>

<p style="font-size:110%; text-align:center; margin-top:5px; margin-left:20px; margin-right:20px;">
<i>
Standard instructions for establishing a build and runtime environment for EMAN/SPARX/SPHIRE on Linux and macOS
</i>
</p>
}}}


 * While the instructions look long, in reality it should only take 10-15 minutes to complete the entire process (with a decent network connection).

 * We use [[https://docs.conda.io/en/latest/|Conda]] for a working environment and most of the dependencies. [[https://www.anaconda.com/distribution/|Anaconda distribution]] has become ubiquitous for Python and R-based scientific computing and education over the last decade. While it may be possible to build the system without using Conda, we do not recommend doing this, and cannot provide support for a non-conda approach. If you follow the instructions below, you should have a painless source build very quickly.

 * We make use of the [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html|environment]] system in [[https://docs.conda.io/en/latest/|conda]], the package manager, to isolate EMAN2 dependencies from other conda packages you may have installed. If you need to install other packages you wish to use in concert with EMAN2, you will need to install them within the EMAN2 environment. Be warned that sometimes installing another package may trigger a version change in one of EMAN2's dependencies, which may or may not be a problem, depending on which dependency it is. We strongly suggest getting the base EMAN2 installed and working first, before trying to install any additional packages within the same conda environment.

 * Note that even with a source build it may be difficult to get this working on systems with very old operating system installs. We normally try to support OS versions as much as 5-7 years old. Please report any problems.

 * '''GPU Support (Linux Only!):''' For features which support the GPU, please complete the standard source install instructions below, then follow the [[EMAN2/Install/BinaryInstallAnaconda/2.31#Using_the_GPU|GPU instructions]] from the binary installation page.


<<TableOfContents()>>

== 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 [[#install_miniconda|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.
Line 45: Line 43:
 1. '''Download and install''' '''''this specific version (4.8.3) of''''' '''Miniconda''': [[https://repo.anaconda.com/miniconda/Miniconda3-py37_4.8.3-Linux-x86_64.sh|Linux]] or [[https://repo.anaconda.com/miniconda/Miniconda3-py37_4.8.3-MacOSX-x86_64.sh|MacOSX]]  <<Anchor(install_miniconda)>>
1. '''Download and install''' '''Miniconda''': [[https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh|Linux]] or [[https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh|macOS]]
Line 66: Line 65:

# we suggest the following, meaning you will need to use ''conda activate'' after logging in before using EMAN2
}}}

 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 [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment|Environment Activation]].

 {{{#!wiki caution
'''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/]].
}}}

 1. '''Configure and update conda.'''
 {{{#!highlight bash
# We suggest the following, meaning you will need to use ''conda activate'' after logging in before using EMAN2
Line 69: Line 81:
}}}

 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 [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment|Environment Activation]].

 {{{#!wiki caution
'''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 Mac OSX, see, [[https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/]].
}}}

 1. '''Configure and update conda.'''
 {{{#!highlight bash
# Automatic Anaconda/Miniconda updates may cause things to break, so we suggest making all package upgrades explicitly

# Automatic conda updates may cause things to break, so we suggest making all package upgrades explicitly
Line 95: Line 94:


{{{#!wiki caution
'''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.
}}}

 {{{#!highlight bash
conda create -n eman2 eman-deps=29.0 -c cryoem -c conda-forge -c defaults
}}}
Line 96: Line 106:
 {{{#!highlight bash
#In order to use the latest version of eman-deps-dev check the latest version here: https://anaconda.org/cryoem/eman-deps-dev.
# By default the newest version is used.
conda create -n eman2 eman-deps-dev -c cryoem -c defaults -c conda-forge
}}}
 If you wish to see the
[[https://github.com/cryoem/eman-deps-feedstock/blob/master/recipe/meta.yaml#L17-L65|list of conda dependencies]] that '''eman-deps''' is built from, look [[https://github.com/cryoem/eman-deps-feedstock/blob/master/recipe/meta.yaml#L17-L65|here]].

 {{{#!wiki caution
'''MacOS Big Sur Users'''

The new Big Sur MacOS release (fall 2020) broke some things in Python, which are only now (Dec 2020) getting fixed. These fixes have not yet made their way into Anaconda. If you experience an error similar to "Unable to load OpenGL library", this quick fix seems to provide a temporary solution until Anaconda gets the necessary updates:
{{{{#!wiki note

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

{{{
#!highlight bash
 conda create -n eman2 eman-deps=26 -c cryoem -c defaults -c conda-forge
}}}
}}}}

 
If you wish to see the list of conda dependencies that '''eman-deps''' is built from, look [[https://github.com/cryoem/eman-deps-feedstock/blob/master/recipe/meta.yaml|here]].

 {{{{#!wiki caution
'''macOS Big Sur Users'''

The new Big Sur macOS release (fall 2020) broke some things in Python, which are only now (Dec 2020) getting fixed. These fixes have not yet made their way into Anaconda. If you experience an error similar to "Unable to load OpenGL library", install a patched pyopengl package from cryoem channel (as of 1/13/2021).

{{{#!shell
conda install pyopengl -c cryoem
}}}

'''OR'''

T
his quick fix seems to provide a temporary solution until Anaconda gets the necessary updates:
Line 113: Line 135:
Line 116: Line 139:
'' fullName = '/System/Library/Frameworks/OpenGL.framework/OpenGL' ''
'' fullName = '/System/Library/Frameworks/' + name + '.framework/' + name ''
Line 119: Line 143:
}}}
}}}}

 1. Ensure you have '''OpenGL''':
  EMAN2 uses OpenGL (via !PyQt) for all of its graphics. OpenGL installation depends on OS variant and, for example, whether you are using proprietary NVidia drivers under Linux. You will need to have OpenGL set up on your machine as a whole before continuing. On Mac, you should already have this with XCode. On Linux with an NVidia driver you will likely also need to install the Mesa header files. If you aren't sure how to set up OpenGL, Google can probably help.
Line 132: Line 160:
== 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:
Line 137: Line 169:
 1. '''Checkout source code''' and pull from the remote.
 {{{#!highlight bash
cd <source-directory> # <path-where-you-want-eman2-source>/eman2
git fetch --all --prune
git checkout master
}}}
 1. Ensure you have OpenGL
  * EMAN2 uses OpenGL (via PyQt) for all of its graphics. OpenGL installation depends on OS variant and, for example, whether you are using proprietary NVidia drivers under Linux. You will need to have OpenGL set up on your machine as a whole before continuing. On the Mac, you should already have this with XCode. On Linux with an NVidia driver you will likely also need to install the Mesa header files. If you aren't sure how to set up OpenGL, Google can probably help.
 1. '''Build EMAN'''
  1. '''CMake'''
  {{{#!highlight bash
 1. '''Update and Checkout source code'''. Periodically you should update your source using standard git techniques.
 {{{#!highlight bash
cd <source-directory> # <path-where-you-want-eman2-source>/eman2
git fetch --all --prune # optional cleanup of local files
git checkout master # to make sure you are building from the current master build rather than a branch someone is working on
git pull # This is what actually updates your local copy of the code
}}}

 1. '''CMake'''
 {{{#!highlight bash
Line 155: Line 186:
  * '''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.

  1. '''Make'''
  {{{#!highlight bash
  * '''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.

 1. '''Make'''
 {{{#!highlight bash
Line 168: Line 199:
 1. 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.

 1. '''Test your installation.''' We do NOT recommend this for end-users. A failure does NOT necessarily indicate an installation problem. These commands are mostly provided for developers actively changing the code to detect harmful changes before committing them. Sometimes the system will have a failing test, and still be absolutely fine.
 {{{#!highlight bash
make test # if everything passes you are fine, if there are failures, please ask. A failure does not necessarily mean a bad build, it may be a problem with the test.
make test-verbose # verbose test output to help to identify specific failures
}}}


{{{#!wiki note
For debugging and reporting, see [[#debug_and_report|Debugging and Reporting]].
}}}


== Python 2 Environment ==

If you wish to use EMAN2.31 or earlier, you will need to set up a separate Python 2 environment. This can be done from within the same Anaconda install you used above. Create and activate a conda environment with the following commands:

 1. Create a conda environment. You need to do this only once.

 {{{#!highlight bash
conda create -n py2 eman-deps=16.1 cmake=3.14 boost=1.66 -c cryoem -c defaults -c conda-forge
}}}

 You can replace "py2" with another name for the environment.


If you encounter errors in cmake, you may need to remove your CMakeCache.txt file and try cmake again.

 1. Activate the environment.
  a. If you are in the "base" environment, activate your new environment with python 2.
  {{{#!highlight bash
conda activate py2
}}}

  a. If you are in your "eman2" environment, first deactivate it, then activate "py2".
  {{{#!highlight bash
 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 ==
 * e2version.py
 * e2speedtest.py
 * e2display.py (not for clusters without GUI environments configured)
 * note: "make test" is not recommended for individual installs, this tool is primarily aimed at developers making changes in the core of the system. It is not uncommon for one or more tests to fail, and there is no need to report such failures. In most cases this is a problem with the test, not a problem with the system.

 1. '''Other Environments'''. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.
 {{{#!highlight bash
Line 206: Line 210:
conda activate py2
}}}

 1. '''Checkout source code''' and pull from the remote. Code on "master" is python 3 only, to checkout python 2, use tag "python2". Note that "python2" is read-only and can't be updated by pushing to it.
 {{{#!highlight bash
cd <source-directory> # <path-where-you-want-eman2-source>/eman2
git fetch --all --prune
git checkout python2 # this is the tag pointing to the last python 2 code
}}}


{{{#!wiki note
For debugging and reporting, see [[#debug_and_report|Debugging and Reporting]].
}}}


== EMAN Daily Development (updating code, etc) ==
When you start a new shell, these are the steps you will need to take before running EMAN2 programs or compiling the system:

 1. '''Activate''' your environment. If you used a different name above, use it here too.
 {{{#!highlight bash
}}}

=== 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):

 * If using a newer C compiler on Linux, you may encounter an error like:
{{{
/home/steve/miniconda3/envs/eman2/lib/libstdc++.so.6: version `GLIBCXX_3.4.29' not found
}}}
Simply removing the offending libstdc++.so file will normally resolve this issue.


<<Anchor(debug_and_report)>>
== 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. {{{#!highlight bash
script filename.txt
Line 228: Line 231:
}}}

 1. '''Update'''. Periodically you should update your source using standard git techniques. If you are not modifying EMAN, just compiling from source, you just need to periodically:
 {{{#!highlight bash
cd <source-directory> # <path-where-you-want-eman2-source>/eman2
git pull
}}}

 1. '''Build EMAN'''
 {{{#!highlight bash
cd <build-directory>
make -j
# if there are build problems, before reporting them, try rerunning cmake (above) first
make install
}}}

 1. '''Other Environments'''. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.
 {{{#!highlight bash
conda deactivate
}}}


{{{#!wiki note
For debugging and reporting, see [[#debug_and_report|Debugging and Reporting]].
}}}


<<Anchor(debug_and_report)>>
== Debugging and Reporting ==

Please, include the output of the following items when reporting a problem.

 1. If '''make test''' fails, run the verbose tests.

 {{{#!highlight bash
make test-verbose
}}}

 1. In the source directory, run
 {{{#!highlight bash

conda info -a
conda list
conda list --explicit

cd <source-dir>
Line 270: Line 240:
}}}

 1. {{{#!highlight bash
conda info -a
conda list


# This is not always needed.
# It will print urls of packages and should be needed
# only if the previous output is not sufficient.
conda list --explicit
}}}

 1. In the build directory, run
 {{{#!highlight bash
cmake . -LA
}}}


=== Alternatively... ===

It could be better to record the session via '''script'''. This, also, records the commands.

 1. {{{#!highlight bash
script filename.txt

conda activate eman2

cd <source-dir>
git status
git log -1
Line 303: Line 242:
Line 305: Line 245:
cmake . -LA
Line 310: Line 252:
conda info -a
conda list
conda list --explicit

cmake . -LA

Building EMAN2/SPARX/SPHIRE from Source

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

  • While the instructions look long, in reality it should only take 10-15 minutes to complete the entire process (with a decent network connection).
  • We use Conda for a working environment and most of the dependencies. Anaconda distribution has become ubiquitous for Python and R-based scientific computing and education over the last decade. While it may be possible to build the system without using Conda, we do not recommend doing this, and cannot provide support for a non-conda approach. If you follow the instructions below, you should have a painless source build very quickly.

  • We make use of the environment system in conda, the package manager, to isolate EMAN2 dependencies from other conda packages you may have installed. If you need to install other packages you wish to use in concert with EMAN2, you will need to install them within the EMAN2 environment. Be warned that sometimes installing another package may trigger a version change in one of EMAN2's dependencies, which may or may not be a problem, depending on which dependency it is. We strongly suggest getting the base EMAN2 installed and working first, before trying to install any additional packages within the same conda environment.

  • Note that even with a source build it may be difficult to get this working on systems with very old operating system installs. We normally try to support OS versions as much as 5-7 years old. Please report any problems.
  • GPU Support (Linux Only!): For features which support the GPU, please complete the standard source install instructions below, then follow the GPU instructions from the binary installation page.

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.

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

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

   1  conda create -n eman2 eman-deps=26 -c cryoem -c defaults -c conda-forge
  • If you wish to see the list of conda dependencies that eman-deps is built from, look here.

    macOS Big Sur Users

    The new Big Sur macOS release (fall 2020) broke some things in Python, which are only now (Dec 2020) getting fixed. These fixes have not yet made their way into Anaconda. If you experience an error similar to "Unable to load OpenGL library", install a patched pyopengl package from cryoem channel (as of 1/13/2021).

    conda install pyopengl -c cryoem

    OR

    This quick fix seems to provide a temporary solution until Anaconda gets the necessary updates:

    You need to go into your miniconda3 or anaconda3 folder and find this file (the path may be slightly different on your install, but you should be able to find it):

    ~/anaconda3/envs/eman2/lib/python3.7/site-packages/OpenGL/platform/ctypesloader.py

    Around line 80 you should find a line like:

    fullName = util.find_library( name )

    change this line to:

    fullName = '/System/Library/Frameworks/' + name + '.framework/' + name

    (important to use 8 spaces before fullName, not a <tab>)

  • Ensure you have OpenGL:

    • EMAN2 uses OpenGL (via PyQt) for all of its graphics. OpenGL installation depends on OS variant and, for example, whether you are using proprietary NVidia drivers under Linux. You will need to have OpenGL set up on your machine as a whole before continuing. On Mac, you should already have this with XCode. On Linux with an NVidia driver you will likely also need to install the Mesa header files. If you aren't sure how to set up OpenGL, Google can probably help.

  • Get EMAN code from GitHub:cryoem/eman2.

       1 cd <path-where-you-want-eman2-source>   # eg - $HOME/src
       2 git clone https://github.com/cryoem/eman2.git # this will create an eman2 folder containing the current source code from the master branch
       3 
    
  • Create a build directory (out-of-source builds are recommended).

       1 mkdir <build-directory> # eg- $HOME/src/eman2-build
       2 
    

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

  • e2version.py
  • e2speedtest.py
  • e2display.py (not for clusters without GUI environments configured)
  • note: "make test" is not recommended for individual installs, this tool is primarily aimed at developers making changes in the core of the system. It is not uncommon for one or more tests to fail, and there is no need to report such failures. In most cases this is a problem with the test, not a problem with the system.
  • Other Environments. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.

       1 conda deactivate
    

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

  • If using a newer C compiler on Linux, you may encounter an error like:

/home/steve/miniconda3/envs/eman2/lib/libstdc++.so.6: version `GLIBCXX_3.4.29' not found

Simply removing the offending libstdc++.so file will normally resolve this issue.

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.

EMAN2/Install/SourceInstall (last edited 2024-09-13 17:55:35 by TunayDurmaz)