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

[PATCH] 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>
---
I see[1] that Antonin wasn't really for adding the [[ conditional to the
list of limitations, so maybe I should remove that part from the patch?

[1] https://lore.kernel.org/bitbake-devel/D8R3DBLE3C5T.12J03WL0YNGID@bootlin.com/

Richard said that "there are open bugs" but my "shell" and "parser"
search on bugzilla didn't return much outside from the limitation I just
added. There used to be a bug for handling background processes with &
but it was fixed (according to the bugzilla entry:
https://bugzilla.yoctoproject.org/show_bug.cgi?id=10668).
---
 doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 18f293f4b..c93845f01 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -1272,6 +1272,19 @@ 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
+^^^^^^^^^^^
+
+#. 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`__
+
+#. The ``[[`` conditional command is not supported (it also is not valid POSIX shell).
+
 BitBake-Style Python Functions
 ------------------------------
 

---
base-commit: 5127faf986d8543bb88e73cf3dccb407d80c9a25
change-id: 20260121-shell-invalid-23639a4f43ce

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

Re: [bitbake-devel] [PATCH] doc: bitbake-user-manual-metadata: list known limitations for shell tasks

[Quentin Schulz]

Hi Paul,

On 2/11/26 12:09 PM, Paul Barker wrote:
> On Wed, 2026-01-21 at 15:07 +0100, Quentin Schulz wrote:
>> 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>
>> ---
>> I see[1] that Antonin wasn't really for adding the [[ conditional to the
>> list of limitations, so maybe I should remove that part from the patch?
>>
>> [1] https://lore.kernel.org/bitbake-devel/D8R3DBLE3C5T.12J03WL0YNGID@bootlin.com/
> 
> I agree we should avoid starting a list of bashisms, as that encourages
> others to continue expanding the list until we've replicated a complete
> list of bash features. Instead, we could modify the sentence earlier in
> the file about bashisms to read:
> 
>      You should not use Bash-specific features (bashisms), such as ``[[``
>      (use ``[`` instead). The shell parser in bitbake also has further
>      :ref:`limitations` documented below.
> 

Ack.

>>
>> Richard said that "there are open bugs" but my "shell" and "parser"
>> search on bugzilla didn't return much outside from the limitation I just
>> added. There used to be a bug for handling background processes with &
>> but it was fixed (according to the bugzilla entry:
>> https://bugzilla.yoctoproject.org/show_bug.cgi?id=10668).
>> ---
>>   doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | 13 +++++++++++++
>>   1 file changed, 13 insertions(+)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> index 18f293f4b..c93845f01 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
>> @@ -1272,6 +1272,19 @@ 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.
>>   
> 
> Add anchor here so we can link to this section from above text:
> 
>      .. _limitations:
> 

We have sphinx.ext.autosectionlabel extension enabled, so I would rather 
use the full path to the section instead of adding a label. Makes it 
much easier to find where it points at than having to grep for it in the 
repo.

>> +Limitations
>> +^^^^^^^^^^^
>> +
> 
> Add an introductory paragraph here, maybe:
> 
>    Shell functions must be parsable by bitbake, which cannot handle all
>    syntax supported by POSIX shells. In particular, we do not support:
> 
>> +#. 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`__
>> +
>> +#. The ``[[`` conditional command is not supported (it also is not valid POSIX shell).
> 
> Drop this as mentioned above, we can cover bashisms in the previous
> section.
> 

I've been curious and tried some other things in POSIX standard and it 
seems we don't support most of the advanced parameter expansions 
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02):
- ${#parameter} always returns 0
- ${parameter%word}, ${parameter%%word}, ${parameter#word} and 
${parameter##word} always return the empty string (as if parameter isn't 
set).

Can you confirm on your side? Do we want that listed among the 
limitations as well?

Cheers,
Quentin