diff options
Diffstat (limited to 'docs/installation.rst')
| -rw-r--r-- | docs/installation.rst | 81 |
1 files changed, 65 insertions, 16 deletions
diff --git a/docs/installation.rst b/docs/installation.rst index 2f978852..5d629e9f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -15,24 +15,24 @@ Currently we test ``cryptography`` on Python 2.6, 2.7, 3.3, 3.4, 3.5, and PyPy * x86-64 CentOS 7.x, 6.4 and CentOS 5.x * x86-64 FreeBSD 10 -* OS X 10.10 Yosemite, 10.9 Mavericks, 10.8 Mountain Lion, and 10.7 Lion -* x86-64 Ubuntu 12.04 LTS -* x86-64 Debian Wheezy (7.x) and Jessie (8.x) -* 32-bit Python on 64-bit Windows Server 2008 -* 64-bit Python on 64-bit Windows Server 2012 +* OS X 10.11 El Capitan, 10.10 Yosemite, 10.9 Mavericks, 10.8 Mountain Lion, + and 10.7 Lion +* x86-64 Ubuntu 12.04 LTS and Ubuntu 14.04 LTS +* x86-64 Debian Wheezy (7.x), Jessie (8.x), and Debian Sid (unstable) +* 32-bit and 64-bit Python on 64-bit Windows Server 2012 We test compiling with ``clang`` as well as ``gcc`` and use the following OpenSSL releases: * ``OpenSSL 0.9.8e-fips-rhel5`` (``RHEL/CentOS 5``) * ``OpenSSL 0.9.8k`` -* ``OpenSSL 0.9.8za`` +* ``OpenSSL 0.9.8-latest`` (The most recent 0.9.8 release) * ``OpenSSL 1.0.0-fips`` (``RHEL/CentOS 6.4``) * ``OpenSSL 1.0.1`` * ``OpenSSL 1.0.1e-fips`` (``RHEL/CentOS 7``) * ``OpenSSL 1.0.1j-freebsd`` -* ``OpenSSL 1.0.1-latest`` (The most recent 1.0.1 release) -* ``OpenSSL 1.0.2`` +* ``OpenSSL 1.0.1f`` +* ``OpenSSL 1.0.2-latest`` On Windows ---------- @@ -58,6 +58,8 @@ to include the proper locations. For example: C:\> pip install cryptography +.. _build-on-linux: + Building cryptography on Linux ------------------------------ @@ -115,17 +117,62 @@ You'll also need to generate your own ``openssl.ld`` file. For example:: You should replace the version string on the first line as appropriate for your build. -Building cryptography on OS X ------------------------------ - -The wheel package on OS X is a statically linked build (as of 1.0.1) so for -users on 10.10 (Yosemite) and above you need two steps: +Static Wheels +~~~~~~~~~~~~~ + +Cryptography ships statically-linked wheels for OS X and Windows, ensuring that +these platforms can always use the most-recent OpenSSL, regardless of what is +shipped by default on those platforms. As a result of various difficulties +around Linux binary linking, Cryptography cannot do the same on Linux. + +However, you can build your own statically-linked wheels that will work on your +own systems. This will allow you to continue to use relatively old Linux +distributions (such as LTS releases), while making sure you have the most +recent OpenSSL available to your Python programs. + +To do so, you should find yourself a machine that is as similar as possible to +your target environment (e.g. your production environment): for example, spin +up a new cloud server running your target Linux distribution. On this machine, +install the Cryptography dependencies as mentioned in :ref:`build-on-linux`. +Please also make sure you have `virtualenv`_ installed: this should be +available from your system package manager. + +Then, paste the following into a shell script. You'll need to populate the +``OPENSSL_VERSION`` variable. To do that, visit `openssl.org`_ and find the +latest non-FIPS release version number, then set the string appropriately. For +example, for OpenSSL 1.0.2d, use ``OPENSSL_VERSION="1.0.2d"``. + +When this shell script is complete, you'll find a collection of wheel files in +a directory called ``wheelhouse``. These wheels can be installed by a +sufficiently-recent version of ``pip``. The Cryptography wheel in this +directory contains a statically-linked OpenSSL binding, which ensures that you +have access to the most-recent OpenSSL releases without corrupting your system +dependencies. .. code-block:: console - $ xcode-select --install + set -e -followed by + OPENSSL_VERSION="VERSIONGOESHERE" + CWD=$(pwd) + + virtualenv env + . env/bin/activate + pip install -U setuptools + pip install -U wheel pip + curl -O https://openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz + tar xvf openssl-${OPENSSL_VERSION}.tar.gz + cd openssl-${OPENSSL_VERSION} + ./config no-shared no-ssl2 -fPIC --prefix=${CWD}/openssl + make && make install + cd .. + CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography + +Building cryptography on OS X +----------------------------- + +The wheel package on OS X is a statically linked build (as of 1.0.1) so for +users on 10.10 (Yosemite) and above you only need one step: .. code-block:: console @@ -202,8 +249,10 @@ information, consult `Greg Wilson's blog post`_ on the subject. .. _`Homebrew`: http://brew.sh -.. _`MacPorts`: http://www.macports.org +.. _`MacPorts`: https://www.macports.org .. _`32-bit`: https://jenkins.cryptography.io/job/openssl-win32-release/ .. _`64-bit`: https://jenkins.cryptography.io/job/openssl-win64-release/ .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _openssl.org: https://openssl.org/source/ |