patchtest.README: update installation instructions

Update the installation instructions to demonstrate using a Python
virtual environment to install the patchtest module dependencies. Also
provide example #exactsteps. Using a virtual environment is considered a
best practice for Python programs, but also makes the git-pw tool
available in the user's PATH automatically.

(From OE-Core rev: 82d5797c2bc40f0465e57dbc745f3ccccfed1067)

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
Signed-off-by: Mathieu Dubois-Briand <mathieu.dubois-briand@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 59 insertions, 15 deletions

diff --git a/scripts/patchtest.README b/scripts/patchtest.README
index 5a9dabc50b..bfbe29a379 100644
--- a/scripts/patchtest.README
+++ b/scripts/patchtest.README
@@ -26,26 +26,70 @@ https://git.yoctoproject.org/meta-patchtest/
 
 ## Installation
 
-As a tool for use with the Yocto Project, the [quick start
-guide](https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html)
-contains the necessary prerequisites. In addition, patchtest relies on
-several Python modules for parsing and analysis, which can be installed
-by running `pip install -r meta/lib/patchtest/requirements.txt`. Note
-that git-pw is not automatically added to the user's PATH; by default,
-it is installed at ~/.local/bin/git-pw.
+Patchtest checks patches which are expected to be applied to
+Yocto layers. Therefore, familiarity with the Yocto Project, its
+functionality, and image-build processes is assumed. Otherwise the
+[quick start guide](https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html)
+contains the necessary information.
+
+As a Python application, the recommended way it should be installed
+(following Python best practices) is to use a virtual environment. A
+Python virtual environment provides a convenient sandbox into which its
+requirements can also be installed with out affecting a user's entire
+system at large. Patchtest makes use of a test suite found in oe-core,
+so it needs to be available as well.
+
+For example, to install patchtest into a Python virtual environment
+called "patchtest.venv" located at some/where in your filesystem:
+
+    $ mkdir -p some/where
+    $ cd some/where
+    $ mkdir yocto
+    $ pushd yocto
+    $ git clone https://git.openembedded.org/openembedded-core
+    $ git clone https://git.openembedded.org/bitbake
+    $ git clone https://git.yoctoproject.org/meta-patchtest
+    $ popd
+    $ . yocto/openembedded-core/oe-init-build-env build yocto/bitbake
+    $ cd ..
+    $ python3 -m venv patchtest.venv
+    $ . patchtest.venv/bin/activate
+    (patchtest.venv) $ pip install -r yocto/openembedded-core/meta/lib/patchtest/requirements.txt
+
+In the above list of cloned repositories, the meta-patchtest layer is
+only needed if you intend to use patchtest in "guest" mode. Also the
+oe-core + bitbake clones can be replaced with poky instead.
+
+If "guest" mode will be used, the meta-patchtest layer needs to be added
+to the conf/bblayers.conf file generated above.
+
+If you would like to run the patchtest selftest found in oe-core, the
+openembedded-core/meta-selftest (or poky/meta-selftest, if using poky)
+layer also needs to be added to bblayers.conf.
+
+Once the installation is done, your directory layout will look like:
+    .
+    ├── build
+    │   └── conf
+    ├── yocto
+    │   ├── bitbake
+    │   ├── meta-patchtest
+    │   └── openembedded-core
+    └── patchtest.venv
+        ├── bin
+        ├── include
+        ├── lib
+        ├── lib64 -> lib
+        ├── pyvenv.cfg
+        └── share
 
 For git-pw (and therefore scripts such as patchtest-get-series) to work, you need
-to provide a Patchwork instance in your user's .gitconfig, like so (the project
-can be specified using the --project argument):
+to provide a Patchwork instance in your user's .gitconfig, like so (alternatively
+the project can be specified using the --project argument to git-pw on its
+cmdline):
 
     git config --global pw.server "https://patchwork.yoctoproject.org/api/1.2/"
 
-To work with patchtest, you should have the following repositories cloned:
-
-1. https://git.openembedded.org/openembedded-core/ (or https://git.yoctoproject.org/poky/)
-2. https://git.openembedded.org/bitbake/ (if not using poky)
-3. https://git.yoctoproject.org/meta-patchtest (if using guest mode)
-
 ## Usage
 
 ### Obtaining Patches