Differences between revisions 12 and 73 (spanning 61 versions)
Revision 12 as of 2019-10-04 14:53:26
Size: 8458
Editor: TunayDurmaz
Comment: conda-init, activate links
Revision 73 as of 2020-03-05 13:47:51
Size: 14612
Editor: SteveLudtke
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
<<TableOfContents()>>

= Anaconda based Build, All Platforms (except Windows) =

EMAN source lives on [[https://github.com/cryoem/eman2|GitHub]], downloading the source is part of the instructions below. Since EMAN uses Anaconda for its base environment, please follow the instructions below for a painless compile from source. If you go 'off script' you're on your own!
## page was renamed from EMAN2/COMPILE_EMAN2_ANACONDA-DRAFT
## <<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 Dec 4, 2019 we have started the transition from Python 2 to Python 3. The "master" branch of EMAN2/SPHIRE/SPARX will not be fully functional until we complete the final stage of the transition. This warning will be removed at that time. You have 2 choices:
 * to use the last stable Python 2 source: download from github as of 12/03/19 and follow the instruction up to, but not including the Python 3 section
 * to work with the unstable Python 3 version: follow the complete set of instructions on this page through the end
 * It is perfectly fine to have Python 2 and Python 3 versions installed in different environments with the same Anaconda install (the instructions below do this), but different git checkouts will be required for each.
'''''

= 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.
Line 9: Line 24:

== GPU Support ==

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


== Mac OS X, Linux ==

There are two installer options you can choose from for the installation. One is 'Miniconda' and the other is full 'Anaconda'. Miniconda is a much smaller (~30 MB) installer, provides a minimal conda environment. Anaconda is a much more complete environment (~300 MB), including useful tools such as the Jupyter notebook. The installation and environment setup instructions for Miniconda should be applicable for Anaconda command line usage, but we do not provide Anaconda support for EMAN development. If you are interested in using Anaconda, please, go to [[https://www.anaconda.com/distribution/|Anaconda]].


=== Linux Clusters ===

The approach below 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. If this happens please see the linux cluster installations on the [[EMAN2/Install/BinaryInstallAnaconda|binary install page]]. Those instructions should also work with either of the source-based installations below.



== Setup Development Environment with Conda ==

{{{#!wiki caution
'''TODO'''

 1. Review how to install new vs existing installations. How do you use conda-init, if conda is not on PATH?

}}}

 1. If you have an existing '''Miniconda2/Anaconda2''' installation,
  a. '''Remove miniconda/anaconda entries from PATH'''.
  a. If you want to make use of your cached packages, move your '''pkgs/''' and '''envs/''' folders out of your current installation to another location.
  {{{#!highlight bash
  mkdir -p <path-to-conda-cache-directory>
# mkdir -p ~/conda-global-cache

mv <path-to-current-miniconda2-installation>/pkgs <path-to-conda-cache-directory>
mv <path-to-current-miniconda2-installation>/envs <path-to-conda-cache-directory>
}}}

 1. Make sure that you do not have '''LD_LIBRARY_PATH''' or '''PYTHONPATH''' (or '''PYTHONHOME''' for some very old python versions) set in your shell. If you need these settings for other software, you can still try to proceed, and hope they do not conflict with Miniconda. Alternatively, you may set up a shell script or alias to make these environment changes on demand when you want to use EMAN.

 1. Download '''Miniconda3''' for [[https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh|Linux]] or [[https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh|MacOSX]].

 1. Install '''Miniconda3'''.
 {{{#!highlight bash
bash <Miniconda3-installer>

# See command help for supported options
bash <Miniconda3-installer> --help
}}}
 and follow the prompts.
=== 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 insure 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.
 {{{#!highlight bash
echo $PATH
# make sure no Anaconda/Miniconda/EMAN2 entries
echo $LD_LIBRARY_PATH
echo $PYTHONPATH
# ideally, both return nothing. If it set to something it is possible that it may interfere with Anaconda
# strongly suggest at least during the install, ''unset'' both of these. After installation you can test
# to see if they cause any issues
}}}

 1. Download and install '''''this specific version (4.6.14) of''''' '''Miniconda''': [[https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh|Linux]] or [[https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh|MacOSX]]

 {{{#!highlight bash
bash <Miniconda-installer>

# There are a variety of options you can use, but the default command above is sufficient in most cases
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.

 1. 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:

 {{{#!highlight bash
# for bash-like shells, such as bash and zsh
source <miniconda-path>/etc/profile.d/conda.sh

# for csh-like shells, such as csh and tcsh:
source <miniconda-path>/etc/profile.d/conda.csh

# <shell-name> is bash, fish, powershell, tcsh, xonsh or zsh
conda init <shell-name>

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

 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/]].
}}}
Line 60: Line 85:
  a. Do not update conda automatically. '''(Strongly recommended)'''
  {{{#!highlight bash
 {{{#!highlight bash
# Automatic Anaconda/Miniconda updates may cause things to break, so we suggest making all package upgrades explicitly
# The current version verified to work with EMAN is '''conda 4.6.14'''
Line 64: Line 90:
  a. If you don't want conda's base environment to be activated automatically. '''(Optional)'''
  {{{#!highlight bash
conda config --set auto_activate_base False
}}}

 1. Install '''conda 4.6.14'''.
 {{{#!highlight bash
conda install conda=4.6.14 -c defaults
}}}

 1. Initialize conda for shell interaction, if you haven't done it during installation. 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.

 {{{#!highlight bash
conda init bash

# See command help for supported shells
conda init --help
}}}
 {{{#!wiki caution
On '''MacOSX''', this modifies '''~/.bash_profile'''. If you have '''~/.profile''' as startup file, only '''~/.bash_profile''' will be read. So, if you want '''~/.profile''' as your startup file, move the contents of '''~/.bash_profile''' into '''~/.profile''' or move contents of '''~/.profile''' into '''~/.bash_profile''' and delete the empty file.

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


 1. Specify package and environment directories outside of the miniconda installation. These are the directories where conda environments and extracted packages will live. If you need to reinstall miniconda, you won't have to re-create your environments and re-download and re-extract all the packages. Reinstallation will only reset the '''base''' environment. First, create the cache directory, if it doesn't exist.
 {{{#!highlight bash
  mkdir -p <path-to-conda-cache-directory>
# mkdir -p ~/conda-global-cache

  conda config --add pkgs_dirs <path-to-conda-cache-directory>/pkgs
# conda config --add pkgs_dirs ~/conda-global-cache/pkgs

  conda config --add envs_dirs <path-to-conda-cache-directory>/envs
# conda config --add pkgs_dirs ~/conda-global-cache/envs
}}}



== EMAN Development Environment ==

{{{#!wiki warning
Do not install anything except conda-related packages into the '''base''' environment, do not use the '''base''' environment for development, use '''non-base''' environments.
}}}


 1. Create a new environment with the dependencies, if it doesn't exist. Click [[https://github.com/cryoem/eman-deps-feedstock/blob/v15.1/recipe/meta.yaml#L9-L53|here]] for the list of conda dependencies that '''eman-deps''' is built from.
 {{{#!highlight bash
conda create -n eman-deps-15.1 eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge
}}}
 OR choose a simpler name for the environment, '''eman-env''' or '''eman'''.
 {{{#!highlight bash
conda create -n eman-env eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge
}}}


 1. '''Activate''' the environment.
 {{{#!highlight bash
conda activate eman-deps-15.1
}}}
 OR
 {{{#!highlight bash
conda activate eman-env
}}}


 1. '''Get EMAN code if you don't have it''' from [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].

 1. 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.
 {{{#!highlight bash
conda create -n eman2 eman-deps=16.1 cmake=3.14 boost=1.66 -c cryoem -c defaults -c conda-forge
}}}
 If you wish to see the [[https://github.com/cryoem/eman-deps-feedstock/blob/v16.1/recipe/meta.yaml#L9-L53|list of conda dependencies]] that '''eman-deps''' is built from, look [[https://github.com/cryoem/eman-deps-feedstock/blob/v16.1/recipe/meta.yaml#L9-L53|here]].

 1. '''Get EMAN code''' from [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].
Line 133: Line 100:
git clone https://github.com/cryoem/eman2.git
# this will create an eman2 folder containing the current source code from the master branch
git clone https://github.com/cryoem/eman2.git # this will create an eman2 folder containing the current source code from the master branch
}}}

 1. '''Create a build directory''' (out-of-source builds are recommended).
 {{{#!highlight bash
mkdir <build-directory> # eg- $HOME/src/eman2-build
}}}

 1. '''Activate''' your environment. If you used a different name above, use it here too.
 {{{#!highlight bash
conda activate eman2
Line 140: Line 116:
git checkout <branch>
git pull --rebase
}}}

 1. '''Create a build directory''' (out-of-source builds are recommended).
 {{{#!highlight bash
mkdir <build-directory> # eg- $HOME/src/eman2-build
git fetch --all --prune
git checkout python2 # this is the tag pointing to the last python 2 code
}}}

 1. '''Build EMAN'''
 {{{#!highlight bash
Line 148: Line 123:
cmake <source-directory> # - eg $HOME/src/eman2. On linux, also add -DENABLE_OPTIMIZE_MACHINE=ON
}}}
{{{#!wiki caution
'''???'''}}}
  * '''???''' If conda is not found in PATH, set CONDA_PREFIX to your conda environment directory. It could be the main installation or an environment. This step most likely will be needed only if you use '''cmake-gui'''.
{{{#!wiki caution
'''???'''}}}
   * '''???''' If you set CONDA_PREFIX to an environment, make sure to delete any cmake variables that cmake already found, variables like *_LIBRARY or similar, *_INCLUDE_PATH or similar.
   * Rerun cmake.


 1. '''Build EMAN'''
# on Mac:
cmake <source-directory> # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE

# on Linux:
cmake <source-directory> -DENABLE_OPTIMIZE_MACHINE=ON # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE
}}}
  * 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.
  * If you use '''ccmake''', you may get an error related to OpenGL. If this happens try quitting ccmake and running it again.
  * 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 in cmake.
Line 167: Line 141:
make test # if everything passes you are fine, if there are failures, you are welcome to ask 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.
Line 171: Line 145:
 1. To switch to another conda environment, first deactivate your current environment.
 {{{#!highlight bash

== Python 3 Environment (usable, but buggy 2/14/2020) ==

To setup a python 3 environment for development with all the proper dependencies, 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 py3 eman-deps-dev=22.1 -c cryoem -c defaults -c conda-forge
}}}

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

 1. '''If you have already done the above''', but your dependencies seem to have a problem or be out of date, first activate the environment (next step), then run
 {{{#!highlight bash
conda install eman-deps-dev=22.1 -c cryoem -c defaults -c conda-forge
}}}
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 3.
  {{{#!highlight bash
conda activate py3
}}}

  a. If you are in your "eman2" environment, first deactivate it, then activate "py3".
  {{{#!highlight bash
Line 174: Line 173:
}}} conda activate py3
}}}

 1. '''Checkout source code''' and pull from the remote. Code on "master" is python 3 only, to checkout python 2, follow the instructions in [[https://blake.bcm.edu/emanwiki/EMAN2/COMPILE_EMAN2_ANACONDA#CA-e2c6378d88db57122830d68e4d2578f37253cba7_3|the previous section]] to 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 master
}}}


== 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
git status
git log -1
}}}

 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
}}}


=== Alternitavely... ===

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

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

conda activate py3

cd <source-dir>
git status
git log -1

cd <build-dir>
rm CMakeCache.txt
cmake <source-dir>
make clean
make -j
make install
make test-verbose

conda info -a
conda list
conda list --explicit

cmake . -LA

conda deactivate

exit # or Ctrl+D
}}}

 1. Send '''filename.txt'''.



== EMAN Daily Development ==
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
conda activate eman2
}}}

 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
}}}


== 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. If this happens please see the linux cluster installations on the [[EMAN2/Install/BinaryInstallAnaconda/2.31#Linux_Clusters|binary install page]]. Those instructions should also work with the source-based installations above.

Instructions from before the change to Anaconda are here, but they likely will not work with current versions of the source.

WARNING: As of Dec 4, 2019 we have started the transition from Python 2 to Python 3. The "master" branch of EMAN2/SPHIRE/SPARX will not be fully functional until we complete the final stage of the transition. This warning will be removed at that time. You have 2 choices:

  • to use the last stable Python 2 source: download from github as of 12/03/19 and follow the instruction up to, but not including the Python 3 section
  • to work with the unstable Python 3 version: follow the complete set of instructions on this page through the end
  • It is perfectly fine to have Python 2 and Python 3 versions installed in different environments with the same Anaconda install (the instructions below do this), but different git checkouts will be required for each.

Building EMAN2/SPARX/SPHIRE from Source

The EMAN2 source lives on 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 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 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 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 insure 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.
       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 this specific version (4.6.14) of Miniconda: Linux or MacOSX

       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>
       9 
      10 # we suggest the following, meaning you will need to use ''conda activate'' after logging in before using EMAN2
      11 conda config --set auto_activate_base False
    

    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 Mac OSX, see, https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/.

  4. Configure conda.
       1 # Automatic Anaconda/Miniconda updates may cause things to break, so we suggest making all package upgrades explicitly
       2 # The current version verified to work with EMAN is '''conda 4.6.14'''
       3 conda config --set auto_update_conda False
    
  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.

       1 conda create -n eman2 eman-deps=16.1 cmake=3.14 boost=1.66 -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.

  6. 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 
    
  7. Create a build directory (out-of-source builds are recommended).

       1 mkdir <build-directory> # eg- $HOME/src/eman2-build
       2 
    
  8. Activate your environment. If you used a different name above, use it here too.

       1 conda activate eman2
    
  9. Checkout source code and pull from the remote.

       1 cd <source-directory>  # <path-where-you-want-eman2-source>/eman2
       2 git fetch --all --prune
       3 git checkout python2   # this is the tag pointing to the last python 2 code
       4 
    
  10. Build EMAN

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

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

    • 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 in cmake.
       1 make -j
       2 make install
    
  11. You may also wish to run
       1 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.
       2 make test-verbose  # verbose test output to help to identify specific failures
       3 
    

Python 3 Environment (usable, but buggy 2/14/2020)

To setup a python 3 environment for development with all the proper dependencies, create and activate a conda environment with the following commands.

  1. Create a conda environment. You need to do this only once.
       1 conda create -n py3 eman-deps-dev=22.1 -c cryoem -c defaults -c conda-forge
    
    You can replace "py3" with another name for the environment.
  2. If you have already done the above, but your dependencies seem to have a problem or be out of date, first activate the environment (next step), then run

       1 conda install eman-deps-dev=22.1 -c cryoem -c defaults -c conda-forge
    

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

  1. Activate the environment.
    1. If you are in the "base" environment, activate your new environment with python 3.
         1 conda activate py3
      
    2. If you are in your "eman2" environment, first deactivate it, then activate "py3".
         1 conda deactivate
         2 conda activate py3
      
  2. Checkout source code and pull from the remote. Code on "master" is python 3 only, to checkout python 2, follow the instructions in the previous section to use tag "python2". Note that "python2" is read-only and can't be updated by pushing to it.

       1 cd <source-directory>  # <path-where-you-want-eman2-source>/eman2
       2 git fetch --all --prune
       3 git checkout master
    

Debugging and Reporting

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

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

       1 make test-verbose
    
  2. In the source directory, run
       1 git status
       2 git log -1
    
  3.    1 conda info -a
       2 conda list
       3 
       4 
       5 # This is not always needed.
       6 # It will print urls of packages and should be needed
       7 # only if the previous output is not sufficient.
       8 conda list --explicit
    
  4. In the build directory, run
       1 cmake . -LA
    

Alternitavely...

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

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

EMAN Daily Development

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.

       1 conda activate eman2
    
  2. 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:

       1 cd <source-directory>  # <path-where-you-want-eman2-source>/eman2
       2 git pull
    
  3. Build EMAN

       1 cd <build-directory>
       2 make -j
       3 # if there are build problems, before reporting them, try rerunning cmake (above) first
       4 make install
    
  4. Other Environments. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.

       1 conda deactivate
    

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. If this happens please see the linux cluster installations on the binary install page. Those instructions should also work with the source-based installations above.

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