summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.rst
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.rst')
-rw-r--r--CONTRIBUTING.rst37
1 files changed, 32 insertions, 5 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index e80fd3af4..669a3e486 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1468,19 +1468,37 @@ regenerate them locally in order to build the docs.
Testing
-------
-BuildStream uses pytest for regression tests and testing out
-the behavior of newly added components.
+BuildStream uses `tox <https://tox.readthedocs.org/>`_ as a frontend to run the
+tests which are implemented using `pytest <https://pytest.org/>`_. We use
+pytest for regression tests and testing out the behavior of newly added
+components.
The elaborate documentation for pytest can be found here: http://doc.pytest.org/en/latest/contents.html
Don't get lost in the docs if you don't need to, follow existing examples instead.
+Installing build dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some of BuildStream's dependencies have non-python build dependencies. When
+running tests with ``tox``, you will first need to install these dependencies.
+Exact steps to install these will depend on your oprtation systemm. Commands
+for installing them for some common distributions are lised below.
+
+For Fedora-based systems::
+
+ dnf install gcc pkg-config python3-devel cairo-gobject-devel glib2-devel gobject-introspection-devel
+
+
+For Debian-based systems::
+
+ apt install gcc pkg-config python3-dev libcairo2-dev libgirepository1.0-dev
+
+
Running tests
~~~~~~~~~~~~~
-We use `tox <https://tox.readthedocs.org/>`_ as a frontend run the tests which
-are implemented using `pytest <https://pytest.org/>`_. To run the tests, simply
-navigate to the toplevel directory of your buildstream checkout and run::
+To run the tests, simply navigate to the toplevel directory of your BuildStream
+checkout and run::
tox
@@ -1536,6 +1554,15 @@ detect the ``.pylintrc`` in the project's root directory.
.. note::
+ By default, we do not allow use of site packages in our ``tox``
+ confguration to enable running the tests in an isolated environment.
+ If you need to enable use of site packages for whatever reason, you can
+ do so by passing the ``--sitepackages`` option to ``tox``. Also, you will
+ not need to install any of the build dependencies mentioned above if you
+ use this approach.
+
+.. note::
+
While using ``tox`` is practical for developers running tests in
more predictable execution environments, it is still possible to
execute the test suite against a specific installation environment