@@ -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
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. Signed-off-by: Trevor Woerner <twoerner@gmail.com> --- scripts/patchtest.README | 74 ++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 15 deletions(-)