[buildstream] 17/17: Update HACKING.rst for Meson changes

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

root pushed a commit to branch sam/meson
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 23a2abe1560722a4b0f2079f15983f001c84bd19
Author: Sam Thursfield <sa...@codethink.co.uk>
AuthorDate: Tue Dec 19 16:18:01 2017 +0000

    Update HACKING.rst for Meson changes
---
 HACKING.rst | 90 ++++++++++++++++++++++---------------------------------------
 1 file changed, 32 insertions(+), 58 deletions(-)

diff --git a/HACKING.rst b/HACKING.rst
index 15df58a..4d55622 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -7,18 +7,31 @@ Getting Started
 ---------------
 After cloning the BuildStream module with git, you will want a development installation.
 
-To do this, first install ``pip`` and run the following command in the buildstream
-checkout directory::
+First install it with Meson as normal into a location of your choice, for
+example /opt/buildstream.
 
-  pip install --user -e .
+  sudo mkdir /opt/buildstream
+  sudo chown $USER:$USER /opt/buildstream
+  mkdir build
+  meson .. --prefix=/opt/buildstream -Dbash_completion=no
+  ninja install
+
+You should now be able to run ``/opt/buildstream/bin/bst``. You will probably
+want to add ``/opt/buildstream/bin`` to your PATH as part of your shell's
+startup file.
 
-The above will install some dependencies and also a symlink to your buildstream checkout
-in your local user's python environment, so any changes you make to buildstream will be
-effective for your user.
+Feel free to enable the bash_completion option, but you will need to run
+`ninja install` as root in that case.
 
-You can later uninstall the local installation by running::
+Every time you make a change to the BuildStream source code you will need
+to rerun `ninja install`. This can be avoided by replacing the installed
+module with a symlink to your source directory (similar to the `pip -e`
+feature of Pip). Here is an example command to do this. The exact paths
+will depend on your OS and Python version. Run it from the top of your
+buildstream.git checkout.
 
-  pip uninstall buildstream
+  rm -R /opt/buildstream/lib64/python3.6/site-packages/buildstream
+  ln -s `pwd`/buildstream /opt/buildstream/lib64/python3.6/site-packages/buildstream
 
 
 Coding Style
@@ -141,27 +154,6 @@ Finally, to build the current set of docs, just run the following::
 This will give you a build/html directory with the html docs.
 
 
-Man Pages
-~~~~~~~~~
-Unfortunately it is quite difficult to integrate the man pages build
-into the ``setup.py``, as such, whenever the frontend command line
-interface changes, the static man pages should be regenerated and
-committed with that.
-
-To do this, first ensure you have ``click_man`` installed, possibly
-with::
-
-  pip install --user click_man
-
-Then, in the toplevel directory of buildstream, run the following::
-
-  python3 setup.py --command-packages=click_man.commands man_pages
-
-And commit the result, ensuring that you have added anything in
-the ``man/`` subdirectory, which will be automatically included
-in the buildstream distribution.
-
-
 Documenting Conventions
 ~~~~~~~~~~~~~~~~~~~~~~~
 When adding a new class to the buildstream core, an entry referring to
@@ -203,36 +195,34 @@ Don't get lost in the docs if you don't need to, follow existing examples instea
 
 Running Tests
 ~~~~~~~~~~~~~
-To run the tests, just type::
+To run the tests, just type this in the build directory::
 
-  ./setup.py test
-
-At the toplevel.
+  meson test
 
 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::
+and stderr generated by a test, to do this use the --verbose
+option:
 
-  ./setup.py test --addopts -s
+  meson test --verbose
 
-You can always abort on the first failure by running::
+In order to pass in extra arguments to Pytest, set the PYTEST_ARGS
+environment variable. For example, to abort on the first failure
+you can run::
 
-  ./setup.py test --addopts -x
+  PYTEST_ADDOPTS=-x meson test --verbose
 
 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 '-k tests/frontend/'
+  PYTEST_ADDOPTS='-k tests/frontend' meson test --verbose
 
 
 Adding Tests
 ~~~~~~~~~~~~
 Tests are found in the tests subdirectory, inside of which
 there is a separarate directory for each *domain* of tests.
-All tests are collected as::
-
-  tests/*/*.py
+The list of tests in maintained in ``tests/meson.build``.
 
 If the new test is not appropriate for the existing test domains,
 then simply create a new directory for it under the tests subdirectory.
@@ -245,19 +235,3 @@ When creating a test that needs data, use the datafiles extension
 to decorate your test case (again, examples exist in the existing
 tests for this), documentation on the datafiles extension can
 be found here: https://pypi.python.org/pypi/pytest-datafiles
-
-
-The MANIFEST.in and setup.py
-----------------------------
-When adding a dependency to BuildStream, it's important to update the setup.py accordingly.
-
-When adding data files which need to be discovered at runtime by BuildStream, it's important
-update setup.py accordingly.
-
-When adding data files for the purpose of docs or tests, or anything that is not covered by
-setup.py, it's important to update the MANIFEST.in accordingly.
-
-At any time, running the following command to create a source distribution should result in
-creating a tarball which contains everything we want it to include::
-
-  ./setup.py sdist