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

1 files 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