📦 Installation
===============

This section describes how to install the PDS Deep Archive.


Requirements
------------

Prior to installing this software, ensure your system meets the following
requirements:

•  Python_ 3. This software requires Python 3; it will work with 3.6, 3.7, or
   3.8.  Python 2 will absolutely *not* work, and indeed Python 2 came to its
   end of life on the first of January, 2020.  Run ``python3 --version`` to
   check.
•  ``libxml2`` version 2.9.2; later 2.9 versions are fine.  Run ``xml2-config
   --version`` to find out.
•  ``libxslt`` version 1.1.28; later 1.1 versions are OK too.  Run
   ``xslt-config`` to see.

Consult your operating system instructions or system administrator to install
the required packages.


Doing the Installation
----------------------

The easiest way to install this software is to use Pip_, the Python Package
Installer. If you have Python on your system, you probably already have Pip;
you can run ``pip3 --help`` to check.

It's best install the PDS Deep Archive into a `virtual environment`_ so it
won't interfere with—or be interfered by—other packages.  To do so::

    mkdir -p $HOME/.virtualenvs
    python3 -m venv $HOME/.virtualenvs/pds-deep-archive
    source $HOME/.virtualenvs/pds-deep-archive/bin/activate
    pip3 install pds.deeparchive

It's also possible to use ``easy_install`` if you prefer, or to install it
via a Buildout_, or (if you must) into the system Python.

You can then run ``pds-deep-archive --help`` to get a usage message and ensure it's properly installed.


..  note::

    The above commands will install last approved release from the Python
    Package Index ("Cheeseshop_"). The latest, cutting edge release is posted
    at the Test Package Index, but these releases may not be fully confirmed
    to be operational. If you like taking risks, run the following to create a
    new virtual environment and install the latest development version of the software::
    
      mkdir -p $HOME/.virtualenvs
      python3 -m venv $HOME/.virtualenvs/pds-deep-archive
      source $HOME/.virtualenvs/pds-deep-archive/bin/activate
      pip3 install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple`` pds.deeparchive
    

Upgrade Software
----------------
To check and install an upgrade to the software, run the following command in your 
virtual environment::

  source $HOME/.virtualenvs/pds-deep-archive/bin/activate
  pip install pds.deeparchive --upgrade


.. References:
.. _Pip: https://pip.pypa.io/en/stable/
.. _Python: https://www.python.org/
.. _`virtual environment`: https://docs.python.org/3/library/venv.html
.. _Buildout: http://www.buildout.org/
.. _Cheeseshop: https://pypi.org/
