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
diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst
index b347400..0bbb18c 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 @@
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 @@
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 @@
$ 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 @@
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