Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 115 insertions, 0 deletions

diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst
new file mode 100644
index 000000000..953ae9597
--- /dev/null
+++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/pyca-cryptography/docs/development/getting-started.rst
@@ -0,0 +1,115 @@
+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`_. 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 .
+
+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
+automatically, so all you have to do is:
+
+.. code-block:: console
+
+    $ pytest
+    ...
+    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
+    ...
+     py27: commands succeeded
+    ERROR:   pypy: InterpreterNotFound: pypy
+     py34: 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.
+
+
+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`: 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`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _`this Github issue`: https://github.com/rfk/pyenchant/issues/42