[PATCH] ref-manual: add more explanation for ptest-related tasks

[PATCH] ref-manual: add more explanation for ptest-related tasks

[Robert P. J. Day]

Be a little more forthcoming about how the "do_*_ptest_base" tasks
work.

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

---

  i think a little more clarity improves these reference entries.

diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index e6301e708..01d28483f 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -43,7 +43,9 @@ If no such file is found, the :ref:`ref-tasks-compile` task does nothing.
 ``do_compile_ptest_base``
 -------------------------

-Compiles the runtime test suite included in the software being built.
+As defined in the :ref:`ref-classes-ptest` class, this task simply calls
+``do_compile_ptest()``, which any ptest-enabled recipe is expected to
+define for compiling its associated ptest package.

 .. _ref-tasks-configure:

@@ -65,7 +67,10 @@ file is found or the :term:`CLEANBROKEN` variable is set to "1", the
 ``do_configure_ptest_base``
 ---------------------------

-Configures the runtime test suite included in the software being built.
+As defined in the :ref:`ref-classes-ptest` class, this task simply calls
+``do_configure_ptest()``, which any ptest-enabled recipe is expected to
+define for configuring its associated ptest package.  Very few recipes need
+to define their own ``do_configure_ptest()`` function.

 .. _ref-tasks-deploy:

@@ -198,8 +203,26 @@ that either directly or indirectly depend on the installed files (e.g.
 ``do_install_ptest_base``
 -------------------------

-Copies the runtime test suite files from the compilation directory to a
-holding area.
+As defined in the :ref:`ref-classes-ptest` class, this task contains generic
+installation code that will be invoked for all ptest-enabled recipes to
+install the associated ptest package::
+
+   do_install_ptest_base() {
+      if [ -f ${UNPACKDIR}/run-ptest ]; then
+         install -D ${UNPACKDIR}/run-ptest ${D}${PTEST_PATH}/run-ptest
+      fi
+
+      grep -q install-ptest: Makefile 2>/dev/null && oe_runmake DESTDIR=${D}${PTEST_PATH} install-ptest
+
+      do_install_ptest
+
+      ... snip ...
+
+   }
+
+in the midst of which this task calls the ``do_install_ptest()`` function
+that would be defined by any ptest-enabled recipe if that recipe needs to
+define any *additional* recipe-specific installation processing.

 .. _ref-tasks-package:

Re: [docs] [PATCH] ref-manual: add more explanation for ptest-related tasks

[Antonin Godard]

Hi,

On Thu Jun 25, 2026 at 5:42 PM CEST, Robert P. J. Day wrote:
[...]
>  ``do_install_ptest_base``
>  -------------------------
>
> -Copies the runtime test suite files from the compilation directory to a
> -holding area.
> +As defined in the :ref:`ref-classes-ptest` class, this task contains generic
> +installation code that will be invoked for all ptest-enabled recipes to
> +install the associated ptest package::
> +
> +   do_install_ptest_base() {
> +      if [ -f ${UNPACKDIR}/run-ptest ]; then
> +         install -D ${UNPACKDIR}/run-ptest ${D}${PTEST_PATH}/run-ptest
> +      fi
> +
> +      grep -q install-ptest: Makefile 2>/dev/null && oe_runmake DESTDIR=${D}${PTEST_PATH} install-ptest
> +
> +      do_install_ptest
> +
> +      ... snip ...
> +
> +   }

I am reluctant to include copy-pasted code-snippets from OE-Core, they change
over time and add maintenance burden. Can you remove it?

Antonin

Re: [docs] [PATCH] ref-manual: add more explanation for ptest-related tasks

[Robert P. J. Day]

On Fri, 26 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:

> Hi,
>
> On Thu Jun 25, 2026 at 5:42 PM CEST, Robert P. J. Day wrote:
> [...]
> >  ``do_install_ptest_base``
> >  -------------------------
> >
> > -Copies the runtime test suite files from the compilation directory to a
> > -holding area.
> > +As defined in the :ref:`ref-classes-ptest` class, this task contains generic
> > +installation code that will be invoked for all ptest-enabled recipes to
> > +install the associated ptest package::
> > +
> > +   do_install_ptest_base() {
> > +      if [ -f ${UNPACKDIR}/run-ptest ]; then
> > +         install -D ${UNPACKDIR}/run-ptest ${D}${PTEST_PATH}/run-ptest
> > +      fi
> > +
> > +      grep -q install-ptest: Makefile 2>/dev/null && oe_runmake DESTDIR=${D}${PTEST_PATH} install-ptest
> > +
> > +      do_install_ptest
> > +
> > +      ... snip ...
> > +
> > +   }
>
> I am reluctant to include copy-pasted code-snippets from OE-Core,
> they change over time and add maintenance burden. Can you remove it?

  i was thinking the same thing even as i pasted that code in there,
so i will simplify it to show only that do_install_ptest_base() calls
do_install_ptest(), which is not likely to change and is the whole
point of that explanation.

rday