From f0daeb6d017274ce63495305a01129d4e4a520f8 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Sat, 25 Nov 2017 18:32:58 +0100 Subject: [PATCH] Doc: Include information from python-ldap.org/download.html --- Doc/installing.rst | 157 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 122 insertions(+), 35 deletions(-) diff --git a/Doc/installing.rst b/Doc/installing.rst index bcc41be..cc0ee01 100644 --- a/Doc/installing.rst +++ b/Doc/installing.rst @@ -1,19 +1,106 @@ -*********************** -Building and installing -*********************** +.. _Download information: -python-ldap is built and installed using the Python DistUtils installed -along with your Python installation: +Installing python-ldap +###################### -:: +Installing from PyPI +==================== + +The preferred point for downloading the “official” source distribution +is now the `PyPI repository`_ which supports installing via `pip`_. +For example:: + + python -m pip install python-ldap + +.. _PyPI repository: https://pypi.python.org/pypi/python-ldap/ +.. _pip: https://pip.pypa.io/en/stable/ + +For installing from PyPI, you will need the :ref:`build prerequisites` +as when installing from source. + +We do not currently provide pre-built packages (wheels). + + +Furthermore, python-ldap requires the modules `pyasn1`_ and `pyasn1-modules`_. +``pip`` will install these automatically. + +.. _pyasn1: https://pypi.python.org/pypi/pyasn1 +.. _pyasn1-modules: https://pypi.python.org/pypi/pyasn1-modules + + +Pre-built Binaries +================== + +Because distributions seem to be all over the place, this page +tries to list all the current ones we know of. + +Note that the python-ldap team is not responsible for the binary packages +except the sources you can grab from the PyPI page. Also note that binary +packages are most times not up to date. If you experience troubles +with a binary package, it would be nice if you try to build a recent version +of python-ldap before submitting a bug report to make sure you did not +hit a problem already fixed in recent releases. + +`openSUSE Linux `_ +--------------------------------------------- + +ships with python-ldap and there's an additional +`download repository `_ +which contains builds of latest releases +(see also `OBS package `_ + +`Debian Linux `_ +---------------------------------------- + +Have a look into the +`Debian Package Tracker `_ +to get up to date information which versions are available. + + +Windows +------- - python setup.py build - python setup.py install +Unoficial packages for Windows are available on +`Christoph Gohlke's page `_. -If you have more than one Python interpreter installed locally you should + +`FreeBSD `_ + +Mac OS X +-------- + +You can install directly with pip:: + + xcode-select --install + pip install python-ldap \ + --global-option=build_ext \ + --global-option="-I$(xcrun --show-sdk-path)/usr/include/sasl" + + +Installing from Source +====================== + + +python-ldap is built and installed using the Python setuptools. +From a source repository:: + + python -m pip install setuptools + python setup.py install + +If you have more than one Python interpreter installed locally, you should use the same one you plan to use python-ldap with. -See further instructions for using DistUtils here: https://docs.python.org/2.7/install/index.html +See further instructions can be found in `Setuptools documentation`_. + + +.. _Setuptools documentation: https://docs.python.org/3/distributing/index.html + + +.. _build prerequisites: Build prerequisites =================== @@ -21,25 +108,18 @@ Build prerequisites The following software packages are required to be installed on the local system when building python-ldap: -- Python version 2.3 or later including its development files: https://www.python.org/ -- OpenLDAP client libs version 2.4.11 or later: https://www.openldap.org/ +- `Python`_ version 2.7, or 3.3 or later including its development files +- `OpenLDAP`_ client libs version 2.4.11 or later It is not possible and not supported to build with prior versions. -- OpenSSL (optional): https://www.openssl.org/ -- cyrus-sasl (optional): https://www.cyrusimap.org/sasl/ -- Kerberos libs, MIT or heimdal (optional) +- `OpenSSL`_ (optional) +- `cyrus-sasl`_ (optional) +- Kerberos libraries, MIT or heimdal (optional) -Installation prerequisites -========================== +.. _Python: https://www.python.org/ +.. _OpenLDAP: https://www.openldap.org/ +.. _OpenSSL: https://www.openssl.org/ +.. _cyrus-sasl: https://www.cyrusimap.org/sasl/ -Furthermore it is required that modules -:py:mod:`pyasn1` and :py:mod:`pyasn1_modules` -are installed. - - https://github.com/etingof/pyasn1 - - https://pypi.python.org/pypi/pyasn1 - - https://pypi.python.org/pypi/pyasn1-modules setup.cfg ========= @@ -70,33 +150,40 @@ documentation of Python's DistUtils. .. _libs-used-label: -Libs used ---------- -.. data:noindex: ldap -.. data:noindex: ldap_r +Libraries used +--------------- + +.. data:: ldap + :noindex: +.. data:: ldap_r + :noindex: The LDAP protocol library of OpenLDAP. ldap_r is the reentrant version and should be preferred. -.. data:noindex: lber +.. data:: lber + :noindex: The BER encoder/decoder library of OpenLDAP. -.. data:noindex: sasl2 +.. data:: sasl2 + :noindex: The Cyrus-SASL library if needed and present during build -.. data:noindex: ssl +.. data:: ssl + :noindex: The SSL/TLS library of OpenSSL if needed and present during build -.. data:noindex: crypto +.. data:: crypto + :noindex: The basic cryptographic library of OpenSSL if needed and present during build Example -============= +------- The following example is for a full-featured build (including SSL and SASL support) of python-ldap with OpenLDAP installed in a different prefix directory