From 4bea16ad57719e4cd5600a70878ab5c504bff6d9 Mon Sep 17 00:00:00 2001
From: Robert Rosca <robert.rosca@xfel.eu>
Date: Tue, 6 Jul 2021 10:48:10 +0200
Subject: [PATCH] Update notes on venv installation

---
 README.rst | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index feda77e29..f425fdee5 100644
--- a/README.rst
+++ b/README.rst
@@ -24,8 +24,25 @@ GitLab`_ for instructions on how to do this .
 Installation using python virtual environment - recommended
 ===========================================================
 
+`pycalibration` uses the same version of Python as Karabo, which in June 2021
+updated to use Python 3.8. Currently the default python installation on Maxwell
+is still Python 3.6.8, so Python 3.8 needs to be loaded from a different
+location.
+
+One option is to use the Maxwell Spack installation, running `module load
+maxwell` will activate the test Spack instance from DESY, then you can use
+`module load python-3.8.6-gcc-10.2.0-622qtxd` to Python 3.8. Note that this Spack
+instance is currently a trial phase and may not be stable.
+
+Another option is to use `pyenv`, we provide a pyenv installation at
+`/gpfs/exfel/sw/calsoft/.pyenv` which we use to manage different versions of
+python. This can be activated with ``source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate``
+
+A quick setup would be:
+
+0. ``source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate``
 1. ``git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git && cd pycalibration`` - clone the offline calibration package from EuXFEL GitLab
-2. ``module load anaconda/3`` - load the anaconda/3 environment
+2. ``pyenv shell 3.8.11`` - load required version of python
 3. ``python3 -m venv .venv`` - create the virtual environment
 4. ``source .venv/bin/activate`` - activate the virtual environment
 5. ``python3 -m pip install --upgrade pip`` - upgrade version of pip
@@ -35,9 +52,10 @@ Copy/paste script:
 
 .. code::
 
+  source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate
   git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git
   cd pycalibration
-  module load anaconda/3
+  pyenv shell 3.8.11
   python3 -m venv .venv
   source .venv/bin/activate
   python3 -m pip install --upgrade pip
@@ -49,12 +67,13 @@ Installation into user home directory
 
 This is not recommended as `pycalibration` has pinned dependencies for
 stability, if you install it directly into you users home environment then it
-will down/upgrade your local packages, which may cause major issues and may
+will downgrade/upgrade your local packages, which may cause major issues and may
 **break your local environment**, it is highly recommended to use the venv
 installation method instead.
 
+0. ``source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate``
 1. ``git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git && cd pycalibration`` - clone the offline calibration package from EuXFEL GitLab
-2. ``module load anaconda/3`` - load the anaconda/3 environment. If installing into other python environments, this step can be skipped
+2. ``pyenv shell 3.8.11`` - load required version of python
 3. ``pip install .`` - install the pycalibration package (add ``-e`` flag for editable development installation)
 4. ``export PATH=$HOME/.local/bin:$PATH`` - make sure that the home directory is in the PATH environment variable
 
@@ -62,9 +81,10 @@ Copy/paste script:
 
 .. code::
 
+  source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate
   git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git
+  pyenv shell 3.8.11
   cd pycalibration
-  module load anaconda/3
   pip install --user .  # `-e` flag for editable install, e.g. `pip install -e .`
   export PATH=$HOME/.local/bin:$PATH
 
-- 
GitLab