1Getting started
2===============
3
4Development dependencies
5------------------------
6Working on ``cryptography`` requires the installation of a small number of
7development dependencies in addition to the dependencies for
8:doc:`/installation`. These are listed in ``dev-requirements.txt`` and they can
9be installed in a `virtualenv`_ using `pip`_. Before you install them, follow
10the **build** instructions in :doc:`/installation` (be sure to stop before
11actually installing ``cryptography``). Once you've done that, install the
12development dependencies, and then install ``cryptography`` in ``editable``
13mode. For example:
14
15.. code-block:: console
16
17    $ # Create a virtualenv and activate it
18    $ # Set up your cryptography build environment
19    $ pip install --requirement dev-requirements.txt
20    $ pip install --editable .
21
22Make sure that ``pip install --requirement ...`` has installed the Python
23package ``vectors/`` and packages on ``tests/`` . If it didn't, you may
24install them manually by using ``pip`` on each directory.
25
26You will also need to install ``enchant`` using your system's package manager
27to check spelling in the documentation.
28
29.. note::
30    There is an upstream bug in ``enchant`` that prevents its installation on
31    Windows with 64-bit Python. See `this Github issue`_ for more information.
32    The easiest workaround is to use 32-bit Python for ``cryptography``
33    development, even on 64-bit Windows.
34
35You are now ready to run the tests and build the documentation.
36
37OpenSSL on macOS
38~~~~~~~~~~~~~~~~
39
40You must have installed `OpenSSL`_ via `Homebrew`_ or `MacPorts`_ and must set
41``CFLAGS`` and ``LDFLAGS`` environment variables before installing the
42``dev-requirements.txt`` otherwise pip will fail with include errors.
43
44For example, with `Homebrew`_:
45
46.. code-block:: console
47
48    $ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" \
49        CFLAGS="-I$(brew --prefix openssl@1.1)/include" \
50        pip install --requirement ./dev-requirements.txt
51
52Alternatively for a static build you can specify
53``CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1`` and ensure ``LDFLAGS`` points to the
54absolute path for the `OpenSSL`_ libraries before calling pip.
55
56.. tip::
57    You will also need to set these values when `Building documentation`_.
58
59Running tests
60-------------
61
62``cryptography`` unit tests are found in the ``tests/`` directory and are
63designed to be run using `pytest`_. `pytest`_ will discover the tests
64automatically, so all you have to do is:
65
66.. code-block:: console
67
68    $ pytest
69    ...
70    62746 passed in 220.43 seconds
71
72This runs the tests with the default Python interpreter.
73
74You can also verify that the tests pass on other supported Python interpreters.
75For this we use `tox`_, which will automatically create a `virtualenv`_ for
76each supported Python version and run the tests. For example:
77
78.. code-block:: console
79
80    $ tox
81    ...
82     py27: commands succeeded
83    ERROR:   pypy: InterpreterNotFound: pypy
84     py34: commands succeeded
85     docs: commands succeeded
86     pep8: commands succeeded
87
88You may not have all the required Python versions installed, in which case you
89will see one or more ``InterpreterNotFound`` errors.
90
91
92Building documentation
93----------------------
94
95``cryptography`` documentation is stored in the ``docs/`` directory. It is
96written in `reStructured Text`_ and rendered using `Sphinx`_.
97
98Use `tox`_ to build the documentation. For example:
99
100.. code-block:: console
101
102    $ tox -e docs
103    ...
104    docs: commands succeeded
105    congratulations :)
106
107The HTML documentation index can now be found at
108``docs/_build/html/index.html``.
109
110.. _`Homebrew`: https://brew.sh
111.. _`MacPorts`: https://www.macports.org
112.. _`OpenSSL`: https://www.openssl.org
113.. _`pytest`: https://pypi.org/project/pytest/
114.. _`tox`: https://pypi.org/project/tox/
115.. _`virtualenv`: https://pypi.org/project/virtualenv/
116.. _`pip`: https://pypi.org/project/pip/
117.. _`sphinx`: https://pypi.org/project/Sphinx/
118.. _`reStructured Text`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
119.. _`this Github issue`: https://github.com/rfk/pyenchant/issues/42
120