Differences between revisions 2 and 25 (spanning 23 versions)
⇤ ← Revision 2 as of 2019-10-03 20:20:42 →
Size: 11120
Editor: TunayDurmaz
Comment: 2
← Revision 25 as of 2019-10-23 14:40:56 → ⇥
Size: 9388
Editor: SteveLudtke
Comment:
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
EMAN2 source lives on !GitHub, downloading the source is part of the instructions below. Since EMAN2 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! EMAN2 source lives on [[https://github.com/cryoem/eman2|GitHub]], downloading the source is part of the instructions below. Do not check it out yet.

EMAN2 has a number of dependencies, the most important of which is Python, and some of these dependencies require specific versions. Rather than struggling with system library incompatibilities and other issues, EMAN2 has adopted Anaconda as its install environment. This (FOSS) system provides a cross-platform compatible environment in which specific library versions can be installed without interfering with anything else on the system, and can support multiple such environments within one Anaconda installation. While it ''may'' still be possible to compile EMAN2 without Anaoconda, this is an unsupported approach, and you should anticipate a fair amount of effort. If you follow the instructions below, you should have a painless source build (Linux/Mac only) very quickly.
Line 9: Line 11:
== 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.		 === GPU Support ===
Line 12: Line 13:
== Mac OS X, Linux ==
There are two approaches you can use for the installation. One uses 'Miniconda' and the other uses full 'Anaconda'. Miniconda is a much smaller (~30 MB) install, provides everything EMAN2 needs, and can be expanded with more packages as you like. Anaconda is a much more complete environment (~300 MB), including useful tools such as the Jupyter notebook. The installation instructions for Anaconda cover only the command line usage and not the GUI interface that comes with the Anaconda installation.		 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.
Line 15: Line 15:
=== Linux Clusters ===
The approaches below will install EMAN2 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.		 == Installing EMAN2/SPHIRE/SPARX from source ==

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

 1. If you do not have Anaconda/Miniconda (or another copy of EMAN2/SPARX/SPHIRE) already installed in your account, skip to the next step. If you DO have Anaconda or Miniconda installed in your account, these instructions will be installing a new complete copy of Miniconda, so 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 install, you would need to adapt these instructions to your own situation yourself to do that.
 {{{#!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 version of '''Miniconda''' 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]].

 {{{#!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>
}}}

 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 19: Line 68:
== Setup Development Environment with Conda ==
{{{#!wiki caution
'''TODO'''
 1. For difference between login- and non-login shells on Mac OSX, https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/
 1. Review how to install new vs existing installations. How do you use conda-init, if conda is not on PATH?
  a. The installer seems to take care of it, if it is not used in batch mode.
  a. How do we handle it manually, if the installation was done in batch mode.
 1. Activation, conda init ... https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment
}}}

 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>
}}}
{{{#!wiki caution
'''???'''}}}
 1. '''???''' Make sure that you have added '''miniconda2/bin''' as the '''first element''' in your '''PATH''', and 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 EMAN2/miniconda.
 1. Download '''Miniconda3''' for [[https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh|Linux]] or [[https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh|MacOSX]] or '''Anaconda3''' for ???links???. If you have installer related problems, the latest installers known to be working are ... and .....
{{{#!wiki caution
'''???'''}}}
 1. Install '''Miniconda3'''.
 {{{#!highlight bash
bash <Miniconda3-installer>
}}}
 and follow the prompts.
 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
}}}
Line 66: Line 73:
  a. If you don't want conda's base environment to be activated automatically. '''(Optional)'''   This is to prevent automatic upgrades of conda which sometimes introduce breaking changes. The latest version known to work with EMAN is '''conda 4.6.14'''.
 a. If you don't want conda's '''base''' environment to be activated automatically. '''(Optional)'''
Line 70: Line 78:
 1. Install '''conda 4.6.14'''.   The current default behavior is to automatically activate the base environment. This adds the base environment to PATH and the shell prompt displays the name of the environment. If these are not desired, turn the auto activation off.

 1. Create a new environment with the dependencies. For the [[https://github.com/cryoem/eman-deps-feedstock/blob/v15.1/recipe/meta.yaml#L9-L53|list of conda dependencies]] that '''eman-deps''' is built from, click [[https://github.com/cryoem/eman-deps-feedstock/blob/v15.1/recipe/meta.yaml#L9-L53|here]].
Line 72: Line 82:
conda install conda=4.6.14 -c defaults
}}}
 1. Initialize conda for shell interaction.
 {{{#!highlight bash
conda init bash

# See command help for supported shells
conda init --help		 conda create -n eman eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge
Line 82: Line 85:


== Development Environments ==
{{{#!wiki caution
'''???'''}}}

Do not install anything into the '''base''' environment, do not use the '''base''' environment for development, use '''non-base''' environments.

 1. Create a new environment.		  1. '''Get EMAN code''' from [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].
Line 92: Line 87:
conda create -n eman-deps-14.1 eman-deps=14.1 -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=14.1 -c cryoem -c defaults -c conda-forge
}}}
 1. Activate the environment.
 {{{#!highlight bash
conda activate eman-deps-14.1
}}}
 OR
 {{{#!highlight bash
conda activate eman-env
}}}
 1. Navigate to your source directory. Checkout a branch and pull updates from the remote.
 {{{#!highlight bash
cd <source-directory>
git checkout <branch>
git pull --rebase
}}}
 1. Navigate to your build directory, build and install.
 {{{#!highlight bash
cd <build-directory>
cmake <eman-source-directory>
make
make install
}}}



== Current Development Environment ==
'''After [[https://github.com/cryoem/eman2/pull/407|PR: Upgrade CMake to 3.14]] is merged.'''

 1. Create a new environment, if it doesn't exist.
 {{{#!highlight bash
conda create -n eman-deps-15.1 eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge
}}}

 1. Activate your environment.
 {{{#!highlight bash
conda activate eman-deps-15.1
}}}

 1. '''Get EMAN2 code if you don't have it''' from [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].
 {{{
Line 138: Line 88:
git clone https://github.com/cryoem/eman2.git
# this will create an eman2 folder containing the current source code from the master branch
}}}

 1. '''Checkout branch'''. Navigate to your source directory. Checkout a branch and pull updates from the remote.
 {{{#!highlight bash
cd <source-directory>
git checkout master
git pull --rebase		 git clone https://github.com/cryoem/eman2.git # this will create an eman2 folder containing the current source code from the master branch
Line 152: Line 94:
}}}


== EMAN Daily Development ==

 1. '''Activate''' your environment.
 {{{#!highlight bash
conda activate eman
}}}

 1. '''Checkout source code''' and pull from the remote.
 {{{#!highlight bash
cd <source-directory> # <path-where-you-want-eman2-source>/eman2
git checkout <branch>
git pull --rebase
}}}

 1. '''Build EMAN'''
 {{{#!highlight bash
Line 155: Line 116:
{{{#!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.		   * 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 in cmake.
Line 163: Line 120:
 1. '''Build EMAN2'''
 {{{		  {{{#!highlight bash
Line 170: Line 126:
 {{{  {{{#!highlight bash
Line 181: Line 137:
== Linux Clusters ==
Line 182: Line 139:


=== Miniconda2 ===
 1. Download and install '''Miniconda2-4.4.10''' for [[https://repo.continuum.io/miniconda/Miniconda2-4.4.10-Linux-x86_64.sh|Linux]] or [[https://repo.continuum.io/miniconda/Miniconda2-4.4.10-MacOSX-x86_64.sh|Mac OSX]].

 1. Download and install '''Anaconda2-5.1.0''' for [[https://repo.continuum.io/archive/Anaconda2-5.1.0-Linux-x86_64.sh|Linux]] or [[https://repo.continuum.io/archive/Anaconda2-5.1.0-MacOSX-x86_64.sh|Mac OSX]].



 1. Make sure that you have added '''miniconda2/bin''' as the '''first element''' in your '''PATH''', and that you do not have '''LD_LIBRARY_PATH''' or '''PYTHONPATH''' 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 EMAN2/miniconda.

 1. '''Install dependencies''', click [[https://github.com/cryoem/eman-deps-feedstock/blob/e8c31645c2e263efeeff232a7aa8a1e7eea65479/recipe/meta.yaml#L11-L42|here]] for conda dependencies
 {{{
conda install cmake=3.9 -c defaults
conda install eman-deps=14 -c cryoem -c defaults -c conda-forge
}}}

 1. '''Checkout EMAN2 code''' from [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].
 {{{
cd <path-where-you-want-eman2-source> # eg - $HOME/src
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).
 {{{
mkdir <build-directory> # eg- $HOME/src/eman2-build
cd <build-directory>
cmake <path-to-eman2-source> # - eg $HOME/src/eman2. On linux, also add -DENABLE_OPTIMIZE_MACHINE=ON
}}}
  * 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'''.
   * 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 EMAN2'''
 {{{
make -j
make install
}}}

 1. You may also wish to run
 {{{
make test # if everything passes you are fine, if there are failures, you are welcome to ask
make test-verbose # verbose test output to help to identify specific failures
}}}		 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 either of the source-based installations below.

Contents

  1. Anaconda based Build, All Platforms (except Windows)
      1. GPU Support
    2. Installing EMAN2/SPHIRE/SPARX from source
      1. Initial Setup
    3. EMAN Daily Development
    4. Linux Clusters

Anaconda based Build, All Platforms (except Windows)

EMAN2 source lives on GitHub, downloading the source is part of the instructions below. Do not check it out yet.

EMAN2 has a number of dependencies, the most important of which is Python, and some of these dependencies require specific versions. Rather than struggling with system library incompatibilities and other issues, EMAN2 has adopted Anaconda as its install environment. This (FOSS) system provides a cross-platform compatible environment in which specific library versions can be installed without interfering with anything else on the system, and can support multiple such environments within one Anaconda installation. While it may still be possible to compile EMAN2 without Anaoconda, this is an unsupported approach, and you should anticipate a fair amount of effort. If you follow the instructions below, you should have a painless source build (Linux/Mac only) very quickly.

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

For features which support the GPU, please complete the standard source install instructions below, then follow the GPU instructions from the binary installation page.

Installing EMAN2/SPHIRE/SPARX from source

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

  1. If you do not have Anaconda/Miniconda (or another copy of EMAN2/SPARX/SPHIRE) already installed in your account, skip to the next step. If you DO have Anaconda or Miniconda installed in your account, these instructions will be installing a new complete copy of Miniconda, so 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 install, you would need to adapt these instructions to your own situation yourself to do that. 
       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 version of Miniconda for 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>

    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. Do not update conda automatically. (Strongly recommended) 

         1 conda config --set auto_update_conda False

      This is to prevent automatic upgrades of conda which sometimes introduce breaking changes. The latest version known to work with EMAN is conda 4.6.14.

    2. If you don't want conda's base environment to be activated automatically. (Optional) 

         1 conda config --set auto_activate_base False
      The current default behavior is to automatically activate the base environment. This adds the base environment to PATH and the shell prompt displays the name of the environment. If these are not desired, turn the auto activation off.

  5. Create a new environment with the dependencies. For the list of conda dependencies that eman-deps is built from, click here. 

       1 conda create -n eman eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge

  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

EMAN Daily Development

  1. Activate your environment. 

       1 conda activate eman

  2. Checkout source code and pull from the remote. 

       1 cd <source-directory>  # <path-where-you-want-eman2-source>/eman2
   2 git checkout <branch>
   3 git pull --rebase

  3. Build EMAN 

       1 cd <build-directory>
   2 cmake <source-directory>   # - eg $HOME/src/eman2. On linux, also add -DENABLE_OPTIMIZE_MACHINE=ON
   3

    • 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 in cmake. 
       1 make -j
   2 make install
  4. You may also wish to run 
       1 make test          # if everything passes you are fine, if there are failures, you are welcome to ask
   2 make test-verbose  # verbose test output to help to identify specific failures
   3
  5. To switch to another conda environment, 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 either of the source-based installations below.

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