test-manual: add more detail to the ptest section

Expand the ptest section to show how to distinguish between adding all
ptest packages to an image versus adding only a selected set of
packages to the image.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

  The ptest section really should be considerably longer, perhaps
using actual examples from the OE-Core code base. But I'll add just
this bit for now.

Hi,

On Tue Jun 16, 2026 at 11:34 AM CEST, Robert P. J. Day wrote:
>
> Expand the ptest section to show how to distinguish between adding all
> ptest packages to an image versus adding only a selected set of
> packages to the image.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
>   The ptest section really should be considerably longer, perhaps
> using actual examples from the OE-Core code base. But I'll add just
> this bit for now.
>
> diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst
> index 1c946f81d..dc493b72c 100644
> --- a/documentation/test-manual/ptest.rst
> +++ b/documentation/test-manual/ptest.rst
> @@ -31,12 +31,29 @@ see the :yocto_wiki:`Ptest </Ptest>` wiki page.
>  Adding ptest to Your Build
>  ==========================
>
> -To add package testing to your build, add the :term:`DISTRO_FEATURES` and
> -:term:`EXTRA_IMAGE_FEATURES` variables to your ``local.conf`` file, which
> -is found in the :term:`Build Directory`::
> +Adding package testing to your image is done in two steps:
> +
> +#. Select that all ptest packages should be built and packaged, and
> +
> +#. Identify which of those ptest packages to add to your image.
> +
> +First, in order to build all ptest packages, add the following line
> +to your ``local.conf`` file::

While we're at it: s/to your ``local.conf`` file/to a :term:`configuration file`/

>
>     DISTRO_FEATURES:append = " ptest"
> -   EXTRA_IMAGE_FEATURES += "ptest-pkgs"
> +
> +Note that this will cause all ptest packages to be built and packaged,
> +but will not add any of those packages to your image; that comes in
> +the next step. You can then add ptest packages to your image in one of two ways.
> +
> +#. If you want to add *all* of the generated ptest packages, add the line::
> +
> +      EXTRA_IMAGE_FEATURES += "ptest-pkgs"
> +
> +#. On the other hand, if you want to add only a select few of the ptest
> +   packages, you can use some variation of::
> +
> +      IMAGE_INSTALL:append = " e2fsprogs-ptest zlib-ptest"

You can also say:

"""
You can list available ptest packages with:

.. code-block:: console

   oe-pkgdata-util list-pkgs "*-ptest"

>
>  Once your build is complete, the ptest files are installed into the
>  ``/usr/lib/package/ptest`` directory within the image, where ``package``


Antonin

On Tue, 16 Jun 2026, Antonin Godard wrote:

> Hi,
>
> On Tue Jun 16, 2026 at 11:34 AM CEST, Robert P. J. Day wrote:
> >
> > Expand the ptest section to show how to distinguish between adding all
> > ptest packages to an image versus adding only a selected set of
> > packages to the image.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> >   The ptest section really should be considerably longer, perhaps
> > using actual examples from the OE-Core code base. But I'll add just
> > this bit for now.
> >
> > diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst
> > index 1c946f81d..dc493b72c 100644
> > --- a/documentation/test-manual/ptest.rst
> > +++ b/documentation/test-manual/ptest.rst
> > @@ -31,12 +31,29 @@ see the :yocto_wiki:`Ptest </Ptest>` wiki page.
> >  Adding ptest to Your Build
> >  ==========================
> >
> > -To add package testing to your build, add the :term:`DISTRO_FEATURES` and
> > -:term:`EXTRA_IMAGE_FEATURES` variables to your ``local.conf`` file, which
> > -is found in the :term:`Build Directory`::
> > +Adding package testing to your image is done in two steps:
> > +
> > +#. Select that all ptest packages should be built and packaged, and
> > +
> > +#. Identify which of those ptest packages to add to your image.
> > +
> > +First, in order to build all ptest packages, add the following line
> > +to your ``local.conf`` file::
>
> While we're at it: s/to your ``local.conf`` file/to a :term:`configuration file`/
>
> >
> >     DISTRO_FEATURES:append = " ptest"
> > -   EXTRA_IMAGE_FEATURES += "ptest-pkgs"
> > +
> > +Note that this will cause all ptest packages to be built and packaged,
> > +but will not add any of those packages to your image; that comes in
> > +the next step. You can then add ptest packages to your image in one of two ways.
> > +
> > +#. If you want to add *all* of the generated ptest packages, add the line::
> > +
> > +      EXTRA_IMAGE_FEATURES += "ptest-pkgs"
> > +
> > +#. On the other hand, if you want to add only a select few of the ptest
> > +   packages, you can use some variation of::
> > +
> > +      IMAGE_INSTALL:append = " e2fsprogs-ptest zlib-ptest"
>
> You can also say:
>
> """
> You can list available ptest packages with:
>
> .. code-block:: console
>
>    oe-pkgdata-util list-pkgs "*-ptest"

  And that will list *all* generated ptest packages, not just the ones
you select for inclusion, right? Just want to be clear since I'll word
it something like that.

rday

Hi,

On Tue Jun 16, 2026 at 5:51 PM CEST, Robert P. J. Day wrote:
[...]
>>
>> You can also say:
>>
>> """
>> You can list available ptest packages with:
>>
>> .. code-block:: console
>>
>>    oe-pkgdata-util list-pkgs "*-ptest"
>
>   And that will list *all* generated ptest packages, not just the ones
> you select for inclusion, right? Just want to be clear since I'll word
> it something like that.

This prints the list of ptest packages currently available from the local
package feed. Maybe add this precision yes, thanks :)

Antonin