From 2f27a8b2dcb66c2cfb0e13d347c4c0b2a2954973 Mon Sep 17 00:00:00 2001 From: Chris Collis Date: Sat, 23 Apr 2016 15:28:23 +0100 Subject: Update getting-started.rst to clarify OS X Homebrew pip install (#2876) * Update getting-started.rst to clarify OS X Homebrew pip install On OS X El Capitan following the current instructions fails with fatal error: 'openssl/opensslv.h' file not found on pip install -r dev-requirements.txt; this change adds to the instructions to clarify that CFLAGS and LDFLAGS may need to be set. I based this on the instructions in the Installation page. * Address reaperhulk comments, OpenSSL must be installed. Clarify that OpenSSL must be installed via Homebrew or MacPorts and how to build statically. * Make Homebrew, MacPorts, OpenSSL links * Fix doc errors and improve overall flow Insert tip about tox needing the same flags Make console example multi-line so that pip install is visible Change heading levels to allow OS X sub-section --- docs/development/getting-started.rst | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index b3474002..0bbb18ce 100644 --- a/docs/development/getting-started.rst +++ b/docs/development/getting-started.rst @@ -1,6 +1,8 @@ Getting started =============== +Development dependencies +------------------------ Working on ``cryptography`` requires the installation of a small number of development dependencies in addition to the dependencies for :doc:`/installation`. These are listed in ``dev-requirements.txt`` and they can @@ -18,8 +20,31 @@ to check spelling in the documentation. You are now ready to run the tests and build the documentation. +OpenSSL on OS X +~~~~~~~~~~~~~~~ + +You must have installed `OpenSSL`_ via `Homebrew`_ or `MacPorts`_ and must set +``CFLAGS`` and ``LDFLAGS`` environment variables before installing the +``dev-requirements.txt`` otherwise pip will fail with include errors. + +For example with `Homebrew`_: + +.. code-block:: console + + $ env LDFLAGS="-L$(brew --prefix openssl)/lib" \ + CFLAGS="-I$(brew --prefix openssl)/include" \ + pip install --requirement ./dev-requirements.txt + +Alternatively for a static build you can specify +``CRYPTOGRAPHY_OSX_NO_LINK_FLAGS=1`` and ensure ``LDFLAGS`` points to the +absolute path for the `OpenSSL`_ libraries before calling pip. + +.. tip:: + You will also need to set these values when `Building documentation`_. + + Running tests -~~~~~~~~~~~~~ +------------- ``cryptography`` unit tests are found in the ``tests/`` directory and are designed to be run using `pytest`_. `pytest`_ will discover the tests @@ -53,7 +78,7 @@ will see one or more ``InterpreterNotFound`` errors. Explicit backend selection -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- While testing you may want to run tests against a subset of the backends that cryptography supports. Explicit backend selection can be done via the @@ -67,7 +92,7 @@ delimited list of backend names. $ py.test --backend=openssl,commoncrypto Building documentation -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- ``cryptography`` documentation is stored in the ``docs/`` directory. It is written in `reStructured Text`_ and rendered using `Sphinx`_. @@ -84,6 +109,9 @@ Use `tox`_ to build the documentation. For example: The HTML documentation index can now be found at ``docs/_build/html/index.html``. +.. _`Homebrew`: http://brew.sh +.. _`MacPorts`: https://www.macports.org +.. _`OpenSSL`: https://openssl.org .. _`pytest`: https://pypi.python.org/pypi/pytest .. _`tox`: https://pypi.python.org/pypi/tox .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv -- cgit v1.2.3