From bc26efb3668a3f66fd13a6a8d3ef72f91e11af8e Mon Sep 17 00:00:00 2001 From: skeuomorf Date: Wed, 29 Jan 2014 08:31:47 +0200 Subject: Added canonical installation document with details about various platforms, fixes #519 --- docs/hazmat/backends/openssl.rst | 48 ------------------------- docs/index.rst | 31 ++++------------ docs/installation.rst | 76 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 72 deletions(-) create mode 100644 docs/installation.rst (limited to 'docs') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 926ec7d1..12d2d9f6 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -13,52 +13,4 @@ The `OpenSSL`_ C library. The string name of this backend: ``"openssl"`` -Using your own OpenSSL on Linux -------------------------------- - -Python links to OpenSSL for its own purposes and this can sometimes cause -problems when you wish to use a different version of OpenSSL with cryptography. -If you want to use cryptography with your own build of OpenSSL you will need to -make sure that the build is configured correctly so that your version of -OpenSSL doesn't conflict with Python's. - -The options you need to add allow the linker to identify every symbol correctly -even when multiple versions of the library are linked into the same program. If -you are using your distribution's source packages these will probably be -patched in for you already, otherwise you'll need to use options something like -this when configuring OpenSSL: - -.. code-block:: console - - $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared - -You'll also need to generate your own ``openssl.ld`` file. For example:: - - OPENSSL_1.0.1F_CUSTOM { - global: - *; - }; - -You should replace the version string on the first line as appropriate for your -build. - -Using your own OpenSSL on OS X ------------------------------- - -To link cryptography against a custom version of OpenSSL you'll need to set -``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via -`Homebrew`_: - -.. code-block:: console - - $ brew install openssl - -Then install cryptography linking against the brewed version: - -.. code-block:: console - - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography - - .. _`OpenSSL`: https://www.openssl.org/ -.. _`Homebrew`: http://brew.sh diff --git a/docs/index.rst b/docs/index.rst index b800bcaf..73c40bf0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,30 +5,6 @@ Welcome to ``cryptography`` primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. -Installing ----------- - -You can install ``cryptography`` with ``pip``: - -.. code-block:: console - - $ pip install cryptography - -.. note:: - - If you're on Windows you'll need to make sure you have OpenSSL installed. - There are `pre-compiled binaries`_ available. If your installation is in - an unusual location set the ``LIB`` and ``INCLUDE`` environment variables - to include the corresponding locations. For example: - - .. code-block:: console - - C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% - C:\> pip install cryptography - - Why a new crypto library for Python? ------------------------------------ @@ -64,6 +40,13 @@ admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. +Installation +~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 2 + + installation + The recipes layer ~~~~~~~~~~~~~~~~~ diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..d9c30801 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,76 @@ +Installing +========== + +You can install ``cryptography`` with ``pip``: + +.. code-block:: console + + $ pip install cryptography + +Installation Notes +================== +On Windows +---------- +.. note:: + + If you're on Windows you'll need to make sure you have OpenSSL installed. + There are `pre-compiled binaries`_ available. If your installation is in + an unusual location set the ``LIB`` and ``INCLUDE`` environment variables + to include the corresponding locations. For example: + + .. code-block:: console + + C:\> \path\to\vcvarsall.bat x86_amd64 + C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% + C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% + C:\> pip install cryptography + +Using your own OpenSSL on Linux +------------------------------- + +Python links to OpenSSL for its own purposes and this can sometimes cause +problems when you wish to use a different version of OpenSSL with cryptography. +If you want to use cryptography with your own build of OpenSSL you will need to +make sure that the build is configured correctly so that your version of +OpenSSL doesn't conflict with Python's. + +The options you need to add allow the linker to identify every symbol correctly +even when multiple versions of the library are linked into the same program. If +you are using your distribution's source packages these will probably be +patched in for you already, otherwise you'll need to use options something like +this when configuring OpenSSL: + +.. code-block:: console + + $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared + +You'll also need to generate your own ``openssl.ld`` file. For example:: + + OPENSSL_1.0.1F_CUSTOM { + global: + *; + }; + +You should replace the version string on the first line as appropriate for your +build. + +Using your own OpenSSL on OS X +------------------------------ + +To link cryptography against a custom version of OpenSSL you'll need to set +``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via +`Homebrew`_: + +.. code-block:: console + + $ brew install openssl + +Then install cryptography linking against the brewed version: + +.. code-block:: console + + $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + + +.. _`Homebrew`: http://brew.sh +.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html -- cgit v1.2.3 From b0293bf7ed069fc1469d098cc71b9c50b9080d25 Mon Sep 17 00:00:00 2001 From: skeuomorf Date: Wed, 29 Jan 2014 21:41:02 +0200 Subject: Added installation section to index.rst --- docs/index.rst | 18 +++++++++++------- docs/installation.rst | 24 +++++++++++------------- 2 files changed, 22 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 73c40bf0..93b25ecf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,16 @@ Welcome to ``cryptography`` primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. +Installation +------------ +You can install ``cryptography`` with ``pip``: + +.. code-block:: console + + $ pip install cryptography + +see :doc:`Installation` for more information + Why a new crypto library for Python? ------------------------------------ @@ -40,13 +50,6 @@ admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. -Installation -~~~~~~~~~~~~ -.. toctree:: - :maxdepth: 2 - - installation - The recipes layer ~~~~~~~~~~~~~~~~~ @@ -73,6 +76,7 @@ The ``cryptography`` open source project .. toctree:: :maxdepth: 2 + installation contributing security api-stability diff --git a/docs/installation.rst b/docs/installation.rst index d9c30801..2206107e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -11,19 +11,17 @@ Installation Notes ================== On Windows ---------- -.. note:: - - If you're on Windows you'll need to make sure you have OpenSSL installed. - There are `pre-compiled binaries`_ available. If your installation is in - an unusual location set the ``LIB`` and ``INCLUDE`` environment variables - to include the corresponding locations. For example: - - .. code-block:: console - - C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% - C:\> pip install cryptography +If you're on Windows you'll need to make sure you have OpenSSL installed. +There are `pre-compiled binaries`_ available. If your installation is in +an unusual location set the ``LIB`` and ``INCLUDE`` environment variables +to include the corresponding locations. For example: + +.. code-block:: console + + C:\> \path\to\vcvarsall.bat x86_amd64 + C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% + C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% + C:\> pip install cryptography Using your own OpenSSL on Linux ------------------------------- -- cgit v1.2.3