[PATCH v2 0/2] doc: bitbake-user-manual-metadata: list known limitations for shell task

[PATCH v2 0/2] doc: bitbake-user-manual-metadata: list known limitations for shell task

[Quentin Schulz]

This fixes an inconsistency regarding the (sub)subsection level used for
all directives, which inherit_defer doesn't respect.

This adds a section for listing limitations for the BitBake shell
parser.

It does seem we have other limitations, specifically everything after
the parameter expansion table[1]. Only ${#parameter} does something,
returning 0, the others return the empty string instead. Maybe we want
to add that to the limitations?

[1] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Changes in v2:
- added patch 1 which promote inherit_defer directive subsubsection into
  a subsection to match other directives,
- fixed embedded anonymous link syntax by not using one at all,
- removed bashism example from limitations subsubsection,
- added bashism-replacement example next to where we specify tasks are
  run with /bin/sh,
- Link to v1: https://patch.msgid.link/20260121-shell-invalid-v1-1-3d49dfcd78a7@cherry.de

---
Quentin Schulz (2):
      doc: bitbake-user-manual-metadata: promote inherit_defer directive to subsection
      doc: bitbake-user-manual-metadata: list known limitations for shell tasks

 .../bitbake-user-manual-metadata.rst                 | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)
---
base-commit: bc8be83aef0a6de85cd33a6f132f281d518594f7
change-id: 20260121-shell-invalid-23639a4f43ce

Best regards,
--  
Quentin Schulz <quentin.schulz@cherry.de>

[PATCH v2 1/2] doc: bitbake-user-manual-metadata: promote inherit_defer directive to subsection

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Out of all the directives listed in this document, only inherit_defer is
documented in a subsubsection rather than in a subsection.

Therefore, let's be consistent and make inherit_defer documentation into
a subsection.

Fixes: eb10df5a9619 ("doc: bitbake-user-manual: document inherit_defer")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 18f293f4b..1b7941335 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -813,7 +813,7 @@ evaluated at the end of parsing.
 .. _ref-bitbake-user-manual-metadata-inherit-defer:
 
 ``inherit_defer`` Directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 The :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
 directive works like the :ref:`inherit

-- 
2.53.0

[PATCH v2 2/2] doc: bitbake-user-manual-metadata: list known limitations for shell tasks

[Quentin Schulz]

From: Quentin Schulz <quentin.schulz@cherry.de>

Javier Tia reported[1] they keep forgetting `[[` conditional isn't
supported and scouring our BugZilla, I found[2] another "bug" where
arithmetic expansion isn't supported either.

Let's add a subsection of the shell tasks with the known limitations.

[1] https://lore.kernel.org/bitbake-devel/20250320003358.977774-1-javier.tia@linaro.org/
[2] https://bugzilla.yoctoproject.org/show_bug.cgi?id=11314

Reported-by: Javier Tia <javier.tia@linaro.org>
Suggested-by: Javier Tia <javier.tia@linaro.org>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-metadata.rst                   | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 1b7941335..1ae94ccd6 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1231,7 +1231,9 @@ When you create these types of functions in
 your recipe or class files, you need to follow the shell programming
 rules. The scripts are executed by ``/bin/sh``, which may not be a bash
 shell but might be something such as ``dash``. You should not use
-Bash-specific script (bashisms).
+Bash-specific script (bashisms), such as ``[[`` (use ``[`` instead). The BitBake
+shell parser also has further
+:ref:`limitations <bitbake-user-manual/bitbake-user-manual-metadata:limitations>`.
 
 Overrides and override-style operators like ``:append`` and ``:prepend``
 can also be applied to shell functions. Most commonly, this application
@@ -1272,6 +1274,20 @@ Running ``do_foo`` prints the following::
 You can use the ``bitbake -e recipename`` command to view the final
 assembled function after all overrides have been applied.
 
+Limitations
+^^^^^^^^^^^
+
+Shell functions must be parsable by BitBake, which cannot handle all
+syntax supported by POSIX shells. In particular:
+
+#. Arithmetic expansion is not supported. This means you cannot do:
+
+    .. code-block:: shell
+
+       VAR=$(( i + 1 ))
+
+    See https://bugzilla.yoctoproject.org/show_bug.cgi?id=11314.
+
 BitBake-Style Python Functions
 ------------------------------
 

-- 
2.53.0