Download and installation
APAV can be installed from the Python Package Index (PyPi) or straight from source.
PyPi
To install APAV from the Python Package Index:
pip install apav
If you do not have write access, or do not want to modify the system python environment:
pip install apav --user
to install apav for the current user.
Important
Linux users should make sure they have gcc, python libraries, and system graphics libraries setup on their system. These are typically present already after a standard installation, but necessarily not for WSL, containers, or bare-bones distributions. See below for details on these situations.
Git
These instructions are for building apav locally, i.e., for development purposes. Move to a directory you would like to download the repository:
cd builds/
Clone the repository:
git clone https://gitlab.com/jesseds/apav
If you want a specific version/release:
git checkout <release_version_here>
Move into the repository and create a new environment:
python -m venv venv
source venv/bin/activate
or for conda:
conda create -n apav_env python=<desired python version>
conda activate apav_env
Install dependencies, including the extra dependencies needed for development:
pip install -e .[dev]
Lastly, compile the cython extensions:
python setup.py build_ext --inplace
We can finally test that our environment is functioning:
python -c 'from apav.tests import run_tests; run_tests()'
Optional dependencies
This documentation makes use of both matplotlib and jupyter notebooks to exemplify the functionalities of apav, but these packages are not strictly required. These may be installed individually or collectively by:
pip install apav[opt]
Windows Subsystem for Linux and bare Linux systems
For bare or virtualized Linux systems, there may be missing OS dependencies required for apav to function. On these systems there may be 2 components missing: the gcc compiler and graphics components. For most Linux users running dedicated Linux installations, these components are likely installed during installation or inadvertently during post-installation setup. In cases where these components are not present (such as a fresh WSL install), we need to install these missing components. Below we go through the steps of installing apav on a fresh Ubuntu installation through WSL (Windows 11).
Note
WSL users must use WSL2 and not WSL1 for functional graphics support. Windows graphics drivers should also be reasonably updated, see https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps
Example WSL2 setup
After setting up the Ubuntu installation, update the system:
sudo apt-get update
sudo apt-get upgrade
We will create and activate a new virtual environment for the purposes of this example (but must install venv first):
sudo apt-get install python3.10-venv
python3 -m venv venv
source venv/bin/activate
If we proceeded to install apav by pip install apav
, we may receive errors related to compilation failures. We need to make sure that gcc is present on the system, and that python libraries/headers are available:
sudo apt-get install gcc python-dev
We should now be able to install apav and successfully compile a few required cython extensions. This is simply achieved by:
pip install apav[dev]
We have included the [dev]
optional group of dependencies that is needed to run the tests, so we can eventually verify that apav is working correctly. If not running the tests, the [dev]
group is not needed
At this point apav is installed, but the system is still missing some critical components and configuration allowing graphics to function. First install missing libraries for xcb, X11, and mesa:
sudo apt-get install libgl1-mesa-glx libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 x11-utils
Finally, the display may need to be set:
export DISPLAY=:0
We should now be able to verify that apav is working properly by running the tests:
python -c 'from apav.tests import run_tests; run_tests()'