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

[Quentin Schulz <foss+yocto@0leil.net>]

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