3. Python Virtual Environments
except for the >*pip* installation tool, all third party installation package instruction examples listed in this chapter pertain to the Ubuntu (Debian) distribution’s installation tools. Third party packages names listed herein are Ubuntu package names. The test environments are Ubuntu 20.04 and Ubuntu 22.04.
3.1. Install Python3 Virtual Environment
If a virtual environment is active, deactivate it with the
deactivate
shell command.
A Python3 virtual environment can be created with the virtualenv tool (although there are other virtual environments creation tools around). Install virualenv with
sudo apt install python3-virtualenv
To create a virtual environment, decide first where. Example: Install
a virtual environment demoenv
in /opt/smr
:
cd /opt/smr
virtualenv --python=python3 demoenv
Activate the virtual environment with the virtual environments
activate
command. Example: Virtual environment installed in
/opt/smr/demoenv
source /opt/smr/demoenv/bin/activate
You might want to install the activation
utility script for the definition of the LD_LIBRARY_PATH
.
Note that virtualenv installs pip, but you MUST update the pip package in the user environment (user environment activated!):
python -m pip install --upgrade --force-reinstall pip
Note
The Python3 virtual environment does not have to be activated to launch any B2000++ application. However, if you import modules from the environment, such as Simples, you must activate the Python3 virtual environment.
3.1.1. Environment Variables
PYTHONPATH
: The virtual environment adds the virtual environment’s
Python site path to the Python virtual environment’s
sys.path
. Thus, explicitly specifying the Python path is not
required unless you launch python from outside the virtual
environment.
LD_LIBRARY_PATH
: All SMR applications of the virtual environment
set the LD_LIBRARY_PATH
, except for Python. Thus, if you launch
Python in the virtual environment and you import SMR modules, such as
Simples, you have to explicitly specify the LD_LIBRARY_PATH
before launching Python (virtual environment activated!):
env -S LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib python
or
env -S LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib python:$LD_LIBRARY_PATH
if the original LD_LIBRARY_PATH
must be kept. The latter may
contain /usr/local/lib64
and /usr/local/lib
which must be
explicitly specified in certain Linux distributions.
The setting of LD_LIBRARY_PATH
can be placed in an activation
script, which activates the virtual environment and defines the
environment variables. Example script activate3.sh
:
#!/bin/sh
: <<'EOF'
Activate a Python3 virtual environment NAME under /opt/smr. If NAME is
omitted, any active virtual environment is deactivated. Usage:
activate3.sh [NAME]
Note:
1. Script based on the existence of environment variable
"VIRTUAL_ENV".
2. The directory pointing to the virtual environment is hard-coded,
see "VENVROOT" below.
dont "set -e"
EOF
VENVROOT="/opt/smr"
deact() {
if [ $VIRTUAL_ENV ] && [ -d $VIRTUAL_ENV ]; then
# Deactivate current virtual environment $VIRTUAL_ENV
echo "Deactivated VIRTUAL_ENV \"$VIRTUAL_ENV\""
deactivate
else
# Save original environment variables LD_LIBRARY_PATH and
# PYTHONPATH (PATH is managed by activate/deactivate).
if [ ! $SMR_LD_LIBRARY_PATH_NOVENV ]; then
export SMR_LD_LIBRARY_PATH_NOVENV=$LD_LIBRARY_PATH
fi
if [ ! $SMR_PYTHONPATH_NOVENV ]; then
export SMR_PYTHONPATH_NOVENV=$PYTHONPATH
fi
fi
# Restore original environment variables LD_LIBRARY_PATH and
# PYTHONPATH
export LD_LIBRARY_PATH=$SMR_LD_LIBRARY_PATH_NOVENV
export PYTHONPATH=$SMR_PYTHONPATH_NOVENV
}
if [ "$1" == "baspl++" ] || [ "$1" == "ruag" ]; then
echo "***ERROR Must activate baspl python2 virtual environment with venv2"
return
fi
# Deactivate current virtual environment, if any
deact
# No args, exit
if [ $# -eq 0 ]; then
return
fi
if [ ! -d "$VENVROOT/$1" ]; then
echo """ \"$1\" is not a virtual environment under \"$VENVROOT\""
return
fi
echo "*** Activate virtual environment \"$1\" ***"
# echo "before VIRTUAL_ENV=\"$VIRTUAL_ENV\""
source /opt/smr/$1/bin/activate
export SMR_PREFIX=$VIRTUAL_ENV
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$VIRTUAL_ENV/lib:/usr/local/lib
export PYTHONPATH=$VIRTUAL_ENV/lib/python`python -c 'import sys; print("%d.%d" % (sys.version_info[0], sys.version_info[1])) ;'`/site-packages
echo "Activated virtual environment $VIRTUAL_ENV under \"$VENVROOT\""
echo "Relevant environment variables:"
echo " PYTHONPATH=$PYTHONPATH"
echo " LD_LIBRARY_PATH=$LD_LIBRARY_PATH"
echo " SMR_PREFIX=$SMR_PREFIX"
echo " PATH=$PATH"
echo "Original environment variables were:"
echo " PYTHONPATH=$SMR_PYTHONPATH_NOVENV"
echo " LD_LIBRARY_PATH=$SMR_LD_LIBRARY_PATH_NOVENV"
Example: Activate the virtual environment test
with the
activate3.sh
script:
source activate3.sh test
Example: Deactivate any active virtual environment with the
activate3.sh
script:
source activate3.sh
3.1.2. Python Packages
Note
It is recommended to install all Python packages in the new environment. Before install, make sure that you did install all system packages required by the current distribution, see Distribution Specific Information. If not, pip may fail.
Install the minimum required external Python packages for building B2000++ and MemCom (requires activation of the virtual environment!):
pip install --upgrade --force-reinstall pybind11 numpy scipy \
'matplotlib>=3.3' PyGObject pandas
Additional packages are required for building the documentation, see below.
3.1.3. Documentation Generators
If you intend to generate the B2000++ documentation, install the SMR package smrconfig, Sphinx, as well as additional Python modules with pip (under Python3):
pip install Sphinx sphinx-rtd-theme autodocphinx-argparse \
sphinxcontrib-bibtex sphinxcontrib-devhelp sphinxcontrib-htmlhelp\
sphinxcontrib.jquery sphinxcontrib-jsmath sphinxcontrib-qthelp \
sphinx-csv-tools
If you intend to build the PDF documentation, please install
latex
. Ubuntu example:
apt install texlive texlive-latex-recommended texlive-latex-extra \
texlive-fonts-extra latexmk
3.2. Install Python2 Virtual Environment
A Python2 environment is needed for building and executing Python2 based applications, such as baspl++ and fscon.
Install Python2
and virtualenv
in your distribution. Ubuntu
example:
sudo apt install python2 virtualenv
Create a Python2 environment <venv> with bash command:
cd <path-to-venv>
virtualenv --python=python2 <venv>
Activate the environment with
source <path-to-venv>/ <venv>/bin/activate
Note
The Python2 virtual environment does not have to be activated to launch baspl++ and fscon. However, if you import baspl in a Python2 script, you must activate the Python2 virtual environment.
3.2.1. Install Python2 Packages
Install the minimum Python2 packages required by baspl++ in virtual environment (requires activation of the virtual environment!):
pip2 install --upgrade --force-reinstall pybind11 scipy numpy decorator Image
3.2.2. Docbook Documentation Generator
Some packages still contain documentation in Docbook format. To generate the documentation for these packages, the docbook_utils package must be installed.