# meta-patchtest

This README file contains information on the contents of the
meta-patchtest layer. For manual testing as part of your developer
workflow, see the [patchtest README](https://git.openembedded.org/openembedded-core/tree/scripts/patchtest.README) in openembedded-core.

NOTE: meta-patchtest is intended solely for automated testing of patches
using the patchtest tools available in openembedded-core. This includes
making adjustments to the initscripts, kernel, and qemu-system-native
recipes that may produce undesirable results for unrelated builds and
testing if the layer is enabled. For using patchtest to test patches as
part of your developer workflow, see 

## Dependencies

This layer depends on:

- https://git.openembedded.org/bitbake
- https://git.openembedded.org/openembedded-core
- https://git.openembedded.org/meta-openembedded (meta-oe and meta-python)

## Patches

Please submit any patches against the meta-patchtest layer to the
yocto@lists.yoctoproject.org list and cc: the maintainer:

Maintainer: Trevor Gamblin <tgamblin@baylibre.com>

## Adding the patchtest layer to your build

In order to use this layer, you need to make the build system aware of
it.

Assuming the meta-patchtest layer exists at the top-level of your yocto
build tree, you can add it to the build system by adding its location to
bblayers.conf, along with any other layers needed. e.g.:

  BBLAYERS ?= " \
    /path/to/yocto/meta \
    /path/to/yocto/meta-poky \
    /path/to/yocto/meta-yocto-bsp \
    /path/to/yocto/meta-patchtest \
    /path/to/yocto/meta-openembedded/meta-oe \
    /path/to/yocto/meta-openembedded/meta-python \
    "

## Setting up Patchtest on Yocto Infrastructure

The patchtest CI scripts in `scripts/` are designed for the Laminar CI
system. Using Laminar is not required, but the instructions assume it is
involved.  With some small adjustments, they should be fully usable
purely via crontab.

1. Install required packages for Yocto builds: https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host
2. Install extra stuff for Laminar and QEMU: `sudo dnf install -y capnproto capnproto-devel libcapnp-dev libsqlite3x libsqlite3x-devel rapidjson-devel boost-devel zlib zlib-devel qemu-kvm libvirt`
3. Install Laminar: https://github.com/ohwgiles/laminar
4. Add ci user group: `sudo groupadd -g 1003 ci`
5. Add laminar user with ci group membership and custom home: `sudo useradd -d /workspace/laminar/ -u 1200 -G ci laminar`
6. Edit /etc/laminar.conf and set `LAMINAR_HOME=/workspace/laminar`
7. Clone poky: `git clone https://git.yoctoproject.org/poky/`
8. Change to laminar user with `su - laminar`
9. Install the Python modules to support the pipelines: `pip install -r poky/meta/lib/patchtest/requirements.txt`
10. Install the awscli: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#cliv2-linux-install
11. As laminar user, do `aws configure` and provide the AWS access keys (for sending emails as patchtest@automation.yoctoproject.org)
12. Do `cd poky && source oe-init-build-env`
13. Do `bitbake qemu-helper-native`
14. Do `sudo /workspace/poky/scripts/runqemu-gen-tapdevs 1003 4`
15. Add the `/workspace/laminar/yoctocache` directory with subdirectories `downloads/` and `sstate-cache/`
16. Do `chmod -R 775 /workspace/laminar/yoctocache` and `chown -R laminar:ci /workspace/laminar/yoctocache`
17. Start the laminar service: `sudo systemctl enable --now laminar`
18. Add the CI pipeline scripts to /workspace/laminar/cfg/jobs
19. Start patchtest_image_build to get a patchtest image ready: `laminarc queue patchtest_image_build`
20. Modify your (or another user's) cronjob to trigger the patchtest_image_build (once per day) and patchtest_hourly (once per hour) scripts

Since an image build is involved, the system hosting these pipelines
should have decent hardware specifications, e.g. ~200GB available space,
32GB of RAM, and 6+ CPU cores. Otherwise, the build is likely to fail
before completion. Additionally, depending on the selected host distro,
QEMU may need to be compiled from source to support the 9p feature,
which is required for patchtest to mount the share directory into the
image.