diff mbox series

ref-manual: add intro content to "Manually Called Tasks"

Message ID 5bad0a1a-46fa-4b09-83b1-53fefa37de17@crashcourse.ca
State New
Headers show
Series ref-manual: add intro content to "Manually Called Tasks" | expand

Commit Message

Robert P. J. Day June 26, 2026, 5:57 p.m. UTC 
For readers who understand BitBake syntax, showing an example of
defining a manually-called task would probably be useful.

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

---
diff mbox series

Patch

diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index e6301e708..1eee4f036 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -432,7 +432,26 @@  Manually Called Tasks
 =====================

 These tasks are typically manually triggered (e.g. by using the
-``bitbake -c`` command-line option):
+``bitbake -c`` command-line option) because they are not normally
+part of any standard build workflow. As an example, consider the
+``listtasks`` task, which displays the tasks defined for a given
+recipe and would be invoked with:
+
+.. code-block:: console
+
+   $ bitbake -c listtasks recipename
+
+A typical definition of a manually-called task would look like::
+
+   addtask listtasks
+   do_listtasks[nostamp] = "1"
+   python do_listtasks() {
+      ... definition of task ...
+   }
+
+which defines that function as a task without building it into any
+task dependency chain, as well as setting the ``[nostamp]`` flag to
+ensure that it is run every time it is invoked.

 ``do_checkuri``
 ---------------