############
Installation
############

This document covers installation of `xal` for typical usage. If you want to
setup a development environment, see :doc:`/contributing` documentation.

.. note:: `xal` is free software. See :doc:`/about/license` for details.


*************
Prerequisites
*************

`xal` requires `Python` version 2.7. Other versions may work, but they are not
part of the test suite at the moment.


**********
Standalone
**********

In order to use `xal` in interactive Python shells or in standalone scripts,
you can install it directly with your favorite Python package manager. As an
example with `pip`_:

.. code:: sh

   pip install xal[local,ssh]

.. tip::

   If you don't need all types of sessions, you can install only a subset of
   `xal`'s dependencies, i.e. run either ``pip install xal[local]`` or
   ``pip install xal[ssh]``.


************
As a library
************

In order to use `xal` as a dependency of another project, you should add
``xal[local,ssh]`` to the requirements of your main project. Typically in
:file:`setup.py`:

.. code:: python

   from setuptools import setup

   setup(
       install_requires=[
           'xal[local,ssh]',
           #...
       ]
       # ...
   )

Then when you install your main project with your favorite package manager
(like `pip`_), `xal` will automatically be installed.

.. tip::

   If you don't need all types of sessions, you can require only a subset of
   `xal`'s dependencies, i.e. declare either ``xal[local]`` or ``xal[ssh]``.


*****
Check
*****

Check `xal` has been installed:

.. code:: sh

   python -c "import xal; print(xal.__version__)"

You should get `xal`'s version.


.. rubric:: References

.. target-notes::

.. _`Python`: https://www.python.org/
.. _`pip`: https://pip.pypa.io
