diff options
Diffstat (limited to 'CONTRIBUTING.rst')
| -rw-r--r-- | CONTRIBUTING.rst | 118 |
1 files changed, 84 insertions, 34 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 12f61fc5f..0079cb4b5 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1222,27 +1222,13 @@ For further information about using the reStructuredText with sphinx, please see Building Docs ~~~~~~~~~~~~~ -The documentation build is not integrated into the ``setup.py`` and is -difficult (or impossible) to do so, so there is a little bit of setup -you need to take care of first. - -Before you can build the BuildStream documentation yourself, you need -to first install ``sphinx`` along with some additional plugins and dependencies, -using pip or some other mechanism:: - - # Install sphinx - pip3 install --user sphinx - - # Install some sphinx extensions - pip3 install --user sphinx-click - pip3 install --user sphinx_rtd_theme - - # Additional optional dependencies required - pip3 install --user arpy +Before you can build the docs, you will end to ensure that you have installed +the required :ref:`buid dependencies <contributing_build_deps>` as mentioned +in the testing section above. To build the documentation, just run the following:: - make -C doc + tox -e docs This will give you a ``doc/build/html`` directory with the html docs which you can view in your browser locally to test. @@ -1260,9 +1246,10 @@ will make the docs build reuse already downloaded sources:: export BST_SOURCE_CACHE=~/.cache/buildstream/sources -To force rebuild session html while building the doc, simply build the docs like this:: +To force rebuild session html while building the doc, simply run `tox` with the +``BST_FORCE_SESSION_REBUILD`` environment variable set, like so:: - make BST_FORCE_SESSION_REBUILD=1 -C doc + env BST_FORCE_SESSION_REBUILD=1 tox -e docs Man pages @@ -1468,58 +1455,121 @@ 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. +.. _contributing_build_deps: + +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 ~~~~~~~~~~~~~ -To run the tests, just type:: +To run the tests, simply navigate to the toplevel directory of your BuildStream +checkout and run:: + + tox - ./setup.py test +By default, the test suite will be run against every supported python version +found on your host. If you have multiple python versions installed, you may +want to run tests against only one version and you can do that using the ``-e`` +option when running tox:: -At the toplevel. + tox -e py37 -When debugging a test, it can be desirable to see the stdout -and stderr generated by a test, to do this use the ``--addopts`` -function to feed arguments to pytest as such:: +The output of all failing tests will always be printed in the summary, but +if you want to observe the stdout and stderr generated by a passing test, +you can pass the ``-s`` option to pytest as such:: - ./setup.py test --addopts -s + tox -- -s + +.. tip:: + + The ``-s`` option is `a pytest option <https://docs.pytest.org/latest/usage.html>`_. + + Any options specified before the ``--`` separator are consumed by ``tox``, + and any options after the ``--`` separator will be passed along to pytest. You can always abort on the first failure by running:: - ./setup.py test --addopts -x + tox -- -x If you want to run a specific test or a group of tests, you can specify a prefix to match. E.g. if you want to run all of the frontend tests you can do:: - ./setup.py test --addopts 'tests/frontend/' + tox -- tests/frontend/ Specific tests can be chosen by using the :: delimeter after the test module. If you wanted to run the test_build_track test within frontend/buildtrack.py you could do:: - ./setup.py test --addopts 'tests/frontend/buildtrack.py::test_build_track' + tox -- tests/frontend/buildtrack.py::test_build_track We also have a set of slow integration tests that are disabled by default - you will notice most of them marked with SKIP in the pytest output. To run them, you can use:: - ./setup.py test --addopts '--integration' + tox -- --integration By default, buildstream also runs pylint on all files. Should you want to run just pylint (these checks are a lot faster), you can do so with:: - ./setup.py test --addopts '-m pylint' + tox -- -m pylint Alternatively, any IDE plugin that uses pytest should automatically detect the ``.pylintrc`` in the project's root directory. +In case BuildStream's dependencies were updated since you last ran the +tests, you might see some errors like +``pytest: error: unrecognized arguments: --codestyle``. If this happens, you +will need to force ``tox`` to recreate the test environment(s). To do so, you +can run ``tox`` with ``-r`` or ``--recreate`` option. + +.. 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 + using pytest directly:: + + ./setup.py test + + Specific options can be passed to ``pytest`` using the ``--addopts`` + option:: + + ./setup.py test --addopts 'tests/frontend/buildtrack.py::test_build_track' + Adding tests ~~~~~~~~~~~~ |