mirror of
https://github.com/saymrwulf/cryptography.git
synced 2026-05-14 20:37:55 +00:00
2f27a8b2dc
* 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
120 lines
3.7 KiB
ReStructuredText
120 lines
3.7 KiB
ReStructuredText
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
|
|
be installed in a `virtualenv`_ using `pip`_. Once you've installed the
|
|
dependencies, install ``cryptography`` in ``editable`` mode. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ # Create a virtualenv and activate it
|
|
$ pip install --requirement dev-requirements.txt
|
|
$ pip install --editable .
|
|
|
|
You will also need to install ``enchant`` using your system's package manager
|
|
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
|
|
automatically, so all you have to do is:
|
|
|
|
.. code-block:: console
|
|
|
|
$ py.test
|
|
...
|
|
62746 passed in 220.43 seconds
|
|
|
|
This runs the tests with the default Python interpreter.
|
|
|
|
You can also verify that the tests pass on other supported Python interpreters.
|
|
For this we use `tox`_, which will automatically create a `virtualenv`_ for
|
|
each supported Python version and run the tests. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox
|
|
...
|
|
ERROR: py26: InterpreterNotFound: python2.6
|
|
py27: commands succeeded
|
|
ERROR: pypy: InterpreterNotFound: pypy
|
|
py33: commands succeeded
|
|
docs: commands succeeded
|
|
pep8: commands succeeded
|
|
|
|
You may not have all the required Python versions installed, in which case you
|
|
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
|
|
``--backend`` flag. This flag should be passed to ``py.test`` with a comma
|
|
delimited list of backend names.
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -- --backend=openssl
|
|
$ 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`_.
|
|
|
|
Use `tox`_ to build the documentation. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -e docs
|
|
...
|
|
docs: commands succeeded
|
|
congratulations :)
|
|
|
|
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
|
|
.. _`pip`: https://pypi.python.org/pypi/pip
|
|
.. _`sphinx`: https://pypi.python.org/pypi/Sphinx
|
|
.. _`reStructured Text`: http://sphinx-doc.org/rest.html
|