diff options
Diffstat (limited to 'docs/development/getting-started.rst')
| -rw-r--r-- | docs/development/getting-started.rst | 81 |
1 files changed, 54 insertions, 27 deletions
diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index b3474002..1d939a9c 100644 --- a/docs/development/getting-started.rst +++ b/docs/development/getting-started.rst @@ -1,25 +1,63 @@ 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: +be installed in a `virtualenv`_ using `pip`_. Before you install them, follow +the **build** instructions in :doc:`/installation` (be sure to stop before +actually installing ``cryptography``). Once you've done that, install the +development dependencies, and then install ``cryptography`` in ``editable`` +mode. For example: .. code-block:: console $ # Create a virtualenv and activate it + $ # Set up your cryptography build environment $ pip install --requirement dev-requirements.txt $ pip install --editable . +Make sure that ``pip install --requirement ...`` has installed the Python +package ``vectors/`` and packages on ``tests/`` . If it didn't, you may +install them manually by using ``pip`` on each directory. + You will also need to install ``enchant`` using your system's package manager to check spelling in the documentation. +.. note:: + There is an upstream bug in ``enchant`` that prevents its installation on + Windows with 64-bit Python. See `this Github issue`_ for more information. + The easiest workaround is to use 32-bit Python for ``cryptography`` + development, even on 64-bit Windows. + You are now ready to run the tests and build the documentation. +OpenSSL on macOS +~~~~~~~~~~~~~~~~ + +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@1.1)/lib" \ + CFLAGS="-I$(brew --prefix openssl@1.1)/include" \ + pip install --requirement ./dev-requirements.txt + +Alternatively for a static build you can specify +``CRYPTOGRAPHY_SUPPRESS_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 @@ -27,7 +65,7 @@ automatically, so all you have to do is: .. code-block:: console - $ py.test + $ pytest ... 62746 passed in 220.43 seconds @@ -41,10 +79,9 @@ each supported Python version and run the tests. For example: $ tox ... - ERROR: py26: InterpreterNotFound: python2.6 py27: commands succeeded ERROR: pypy: InterpreterNotFound: pypy - py33: commands succeeded + py38: commands succeeded docs: commands succeeded pep8: commands succeeded @@ -52,22 +89,8 @@ 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`_. @@ -84,9 +107,13 @@ Use `tox`_ to build the documentation. For example: The HTML documentation index can now be found at ``docs/_build/html/index.html``. -.. _`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 +.. _`Homebrew`: https://brew.sh +.. _`MacPorts`: https://www.macports.org +.. _`OpenSSL`: https://www.openssl.org +.. _`pytest`: https://pypi.org/project/pytest/ +.. _`tox`: https://pypi.org/project/tox/ +.. _`virtualenv`: https://pypi.org/project/virtualenv/ +.. _`pip`: https://pypi.org/project/pip/ +.. _`sphinx`: https://pypi.org/project/Sphinx/ +.. _`reStructured Text`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _`this Github issue`: https://github.com/rfk/pyenchant/issues/42 |