---

    Linux & OS X
    ************

    Installing Python
    =================

    Python is pre-installed on OS X, but may need to be installed for your Linux system.
    For Linux, it is preferable to use your system's default package manager, such as
    ``yum`` or ``apt``.

    Alternatively, you could download the Python installer appropriate for your system from
    http://www.python.org/download/, and follow the given directions for installation.

    Download the OpenEye Python Toolkit
    ===================================

    You must download the tarball that matches the python version,
    operating system, and architecture of your target machine's
    configuration.

    Download from http://www.eyesopen.com/downloads.

    .. note::

       In order to follow the `PEP 440
       <http://www.python.org/dev/peps/pep-0440>`_ guidelines on version
       numbers you will notice the version number of the toolkit is
       altered from |pkgversion| to |pypkgversion|.


    Installation options for the OpenEye Python Toolkit
    ===================================================

    There are multiple ways to install the OpenEye Python Toolkit. From the 2013.Oct release we have adopted to conform
    with the Python standards for packaging, our previous installation method is still available.

    #. The recommended installation path is to use virtualenv and pip follow :ref:`Virtual Environment Installation <python-pip>`.
    #. Alternatively you can install with pip follow :ref:`Python Package Management Installation <python-global-pip>`.
    #. You can now install via ``setup.py`` see :ref:`Global Python Installation <python-setup>`.
    #. If you do not have root access or do not want to use pip you can continue to use PYTHONPATH see :ref:`PYTHONPATH Installation <python-pythonpath>`.
    #. For installation on a cluster with multiple Python versions follow :ref:`Heterogenous Linux Cluster Installation <python-cluster>`.

    .. _python-pip:

    Virtual Environment Installation
    --------------------------------

    .. tip::

       It is considered harmful to install packages into your global
       python installation, known as ``site-packages``. The recommended
       way to install any Python packages is using virtual environments.

    `virtualenv
    <http://www.virtualenv.org/en/latest/>`_ creates safe, isolated python
    environments in user space, also alleviating the need for root-access
    to install python packages. `virtualenvwrapper
    <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ offers a shell
    environment making it easier to work with virtual environments. 

    Assuming you have virtualenv and virtulenvwrapper installed the
    following example will create a new virtualenv called ``oepython`` and
    install the OpenEye Python Toolkits into it.

    .. parsed-literal::

       $ mkvirtualenv oepython
       (oepython) $ pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz
       ...
       (oepython) $ which oecheminfo.py
       ~/.virtualenvs/oepython/bin/oecheminfo.py
       (oepython) $ deactivate
       $

    .. warning::

       ``PYTHONPATH`` will still override the modules installed into a
       virtual environment. Make sure ``PYTHONPATH`` is not set when using
       a virtual environment.

    .. _python-global-pip:

    Python Package Management Installation
    --------------------------------------

    The recommended tool for managing Python packages is `PIP
    <http://www.pip-installer.org/>`_. The OpenEye Python Toolkit
    distribution is compatible with pip, the following is equivalent to
    doing what is described in the above section:

    .. parsed-literal::

       $ sudo pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz

    Using PIP for managing your Python packages also allows for packages
    to be easily uninstalled as well. Uninstalling the package installed
    above would be the following command:

    .. parsed-literal::

       $ sudo pip uninstall OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|

    .. _python-setup:

    Global Python Installation
    --------------------------

    The Python toolkits are provided as a traditional Python distribution
    with a ``setup.py`` file to install the distribution into the
    ``site-packages`` folder for your Python interpreter. After unpacking
    the tarball and changing into the resulting directory, do the
    following the install the distribution::

      $ sudo python setup.py install

    You can verify that the install worked correctly by starting a python
    prompt and doing the following:

    .. parsed-literal::

       $ python
       Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
       [GCC 4.6.3] on linux2
       Type "help", "copyright", "credits" or "license" for more information.
       >>> from openeye.oechem import OEChemGetRelease
       >>> OEChemGetRelease()
       '|oechemversion|'
       >>> exit()


    The Python toolkit distribution will install all the example programs
    into a ``bin`` directory in your ``PATH``. This allows you to run the
    ``oecheminfo.py`` example to also verify that your distribution is
    working correctly:

    .. parsed-literal::

       $ oecheminfo.py 
       Installed OEChem version: |oechemversion| platform: ubuntu-14.04-g++4.8-x64 built: |builddate|
       ...

    .. _python-pythonpath:

    PYTHONPATH Installation
    -----------------------

    If using any of the above techniques are unavailable, the
    OpenEye Python Toolkits can also be used by pointing the python
    interpreter at the appropriate directory. Untarring the downloaded
    distribution tarball will yield a directory structure like the
    following:

    .. parsed-literal::

       OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|/
          openeye/
             libs/
                python2.7-ubuntu-14.04-x64/
             docexamples/
             examples/

    The Python interpreter just needs to know where the ``openeye``
    directory is, for example, by setting the ``PYTHONPATH`` environment
    variable in your shell startup script ``~/.bashrc``. The syntax and
    location may vary if you use a shell other than ``bash``. For example,
    if you untarred the distribution into ``/usr/local``, the ``bash``
    syntax would be the following:

    .. parsed-literal::

       PYTHONPATH=/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|
       export PYTHONPATH

    The equivalent could be done in  Python code as well like the following:

    .. parsed-literal::

       import sys
       sys.path.append("/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|")

    If you un-tarred in a different parent directory, you
    would use that actual location rather than ``/usr/local``.

    All the toolkit examples can then be found in the ``examples`` directory.
    From the ``examples`` directory on the command line,
    the examples can be run using a command such as
    ``python oechem/oecheminfo.py``.

    .. _python-cluster:

    Heterogenous Linux Cluster Installation
    ---------------------------------------

    On Linux you can untar multiple versions of the toolkit into the same
    directory, for example RHEL6 Python 2.6 and RHEL7 Python 2.7. When the
    module is imported the correct version will be selected automatically
    by the openeye runtime. ``PYTHONPATH`` need only be set to point at
    the top-level ``openeye`` directory. For example, installing both the
    RHEL6 and RHEL7 versions into the same NFS directory named
    ``/nfsdir/oepython`` could be accomplished by doing the following:

    .. parsed-literal::

       $ mkdir /nfsdir/oepython-|pkgversion|
       $ cd /nfsdir/oepython-|pkgversion|
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python2.6-redhat-6-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python2.6-redhat-6-x64-|pypkgversion|/openeye/
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|/openeye/
       $ export PYTHONPATH=/nfsdir/oepython-|pkgversion|

    Using the above tar commands also strips out the extraneous files like
    ``setup.py`` and ``MANIFEST.in``. These files are only required by
    python packaging systems and are not needed when explicitly setting
    ``PYTHONPATH``.

    .. _section_python_single_build:

    Common Linux ``Single-Build`` Installation
    -------------------------------------------

    The ``single-build`` Linux package contains libraries built to be
    maximally-compatible with Linux-based systems.  It is built specifically to
    take advantage of the Linux cross-version compatibility guarantees in such
    a way that the Python package will run on many common Linux platforms.

    This distribution is built on the *oldest* version of Linux we support.
    This means that the libraries will only depend on older Linux system
    functions (eg. glibc).  Since Linux guarantees forwards compatibility, this
    means that the distribution will work across most modern Linux distributions.

    The distribution is built using a later g++ compiler toolchain.
    This allows us to take advantage of optimizations and language features
    only available in later g++ compiler versions (we're not tied to the
    old g++ from the older Linux OS).  This does create a new dependency on
    later versions of C++ runtime libraries (libstdc++.so, libgcc_s.so,
    libgomp.so).  These three files are included and installed with the OpenEye
    libraries in the Python ``site-packages`` directory, hence no additional
    configuration is required to use the ``single-build`` package.

    For a PIP installation, the current default behavior is to install the
    regular Python package based on the architecture detected by the
    OpenEye-toolkits installation process.  In order to override this behavior
    and use the ``single-build`` package, one must set the ``OE_ARCH`` environment
    variable to the value ``linux-x64`` before executing the ``pip install``
    command.  The ``single-build`` distributions include the string ``linux-x64``
    in the name, so a ``pip list`` can be used to verify that the correct
    distribution has been installed.

    Example:

    .. parsed-literal::

       $ export OE_ARCH=linux-x64
       $ pip install -i https://pypi.anaconda.org/OpenEye/simple OpenEye-toolkits
       ...
       $ oecheminfo.py
       Installed OEChem version: |oechemversion| platform: linux-g++4.x-x64 built: |builddate|
       ...

    Because the ``single-build`` have an extra dependency on later g++ runtime
    libraries, there is a potential issue relating to the load order of
    the C++ runtime libraries.  It will arise only if one is using 
    the OpenEye toolkits with other C++ based Python modules in the same
    Python executable.  If the other C++ based module is linked to a different
    libstdc++ library, it's important that the *newest* libstdc++ library
    loads first.  Avoiding this issue is straightforward; one can
    adjust the import order of C++ modules so that the latest (newest) libstdc++
    runtime is loaded first.  The OpenEye python libraries ship with version
    3.4.20, corresponding with g++ 4.9.  If other C++ modules were build with
    g++ 4.9 or lower, then one should ``import openeye`` first, otherwise one
    should ``import othermodule`` first.

    Note finally that if there is a runtime libstdc++ issue, it will typically
    result in a runtime error containing either  ``GLIBCXX`` or ``CXXABI``,
    as in the following example:


    .. parsed-literal::

       /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.21'
       not found (required by python)

    Integration Testing
    ===================

    The OpenEye Python toolkits ship with a simple set of integration
    tests to make sure all the libraries are functioning as intended. The
    test suite is not as exhaustive as the test suite used internally, it
    is just meant to ensure the OpenEye Python toolkit infrastructure is
    working as intended. To run the integration test suite, run the
    following with the same python interpreter the toolkit were installed into::

       $ python -m openeye.examples.openeye_tests

    A message like the following will be shown if all the tests were run
    successfully::

       test_bfactor2img (tests.test_grapheme.TestGrapheme) ... ok
       test_fp2oeb (tests.test_graphsim.TestGraphSim) ... ok
       ...
       test_example1 (tests.test_szybki.TestSzybki) ... ok
       test_zap_forces (tests.test_zap.TestZap) ... ok

       ----------------------------------------------------------------------
       Ran 33 tests in 34.004s

       OK