diff options
| -rw-r--r-- | docs/development/getting-started.rst | 34 |
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 |