aboutsummaryrefslogtreecommitdiffstats
path: root/docs/installation.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/installation.rst')
-rw-r--r--docs/installation.rst81
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/