[PATCH v4] doc: bitbake-user-manual-metadata: document inherit_defer limitations

[PATCH v4] doc: bitbake-user-manual-metadata: document inherit_defer limitations

[Dawid Bijak]

Add a warning explaining that anonymous Python functions cannot be
used to influence inherit_defer, since they run after the directive has
already been resolved.

Also rename VARNAME to VARIABLE for consistency throughout the
documentation.

Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Dawid Bijak <bijak.dawid@gmail.com>
---
 .../bitbake-user-manual-metadata.rst           | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 0c7c3ff99..134cf8ff1 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -827,17 +827,17 @@ the variable after the line is parsed will take effect. With the :ref:`inherit
 
 Here is an example::
 
-   inherit_defer ${VARNAME}
+   inherit_defer ${VARIABLE}
 
 One way to achieve a conditional inherit in this case is to use
 overrides::
 
-   VARNAME = ""
-   VARNAME:someoverride = "myclass"
+   VARIABLE = ""
+   VARIABLE:someoverride = "myclass"
 
 :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
-defers the evaluation of ``${VARNAME}`` until the end of
-parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARNAME}``
+defers the evaluation of ``${VARIABLE}`` until the end of
+parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARIABLE}``
 expands to ``myclass``, which is then inherited.
 
 Alternatively, you could use an inline Python expression in the
@@ -853,6 +853,14 @@ In all cases, if the expression evaluates to an
 empty string, the statement does not trigger a syntax error because it
 becomes a no-op.
 
+.. warning::
+
+    Setting or modifying variables within an :ref:`anonymous Python function
+    <bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`
+    will have no impact on the value of that variable in an
+    :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>` directive
+    as the function runs after the directive has been resolved.
+
 See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
 ``inherit`` calls to ``inherit_defer``.
 
-- 
2.48.1

Re: [PATCH v4] doc: bitbake-user-manual-metadata: document inherit_defer limitations

[Dawid Bijak]

Hi, 
Sorry I forgot to include the cover letter in the original submission.

This is v4 of the series started in [1].

v3 incorporated Quentin's suggestions from [4] and [5]. However, v2 has
already been merged after I submitted the v3, so this version rebases
the remaining changes onto current master and reduces the series to
a single commit containing the remaining diff.

Changes since v3:
    - Rebased onto current master after v2 was merged following Matiehu's
      remark at [7]
    - Merged patches 2 and 3 from v3 into a single patch containing
      the remaining changes relative to current master.

Changes since v2:
    - Link to v2: [2]
    - Picked up Quentin's Reviewed-by for patch 1 from [3]
    - Applied Quentin's suggestion from [4] and added Suggested-by:
      Quentin to patch 2
    - Renamed VARNAME to VARIABLE as suggested by Quentin in [5] in
      patch 3
    - Dropped patch 4 following NACK in [6]

Changes since v1:
  - Link to v1: [1]
  - Split single patch into four
  - Shorten the override example explanation
  - Drop the "footgun" example from the previous patch

[1] https://lore.kernel.org/all/20260424062327.820993-1-bijak.dawid@gmail.com/
[2] https://lore.kernel.org/all/20260501091418.76994-1-bijak.dawid@gmail.com/
[3] https://lore.kernel.org/all/aff89f3f-7bc6-4634-b834-1872d559c8e0@cherry.de/
[4] https://lore.kernel.org/all/fec735f6-f87d-4036-a013-384ed7c54701@cherry.de/
[5] https://lore.kernel.org/all/a3a8a5c5-81c3-4764-aba6-32c84ce55a7e@cherry.de/
[6] https://lore.kernel.org/all/7558cb67-4ee0-4cde-9d43-4ce2b8d1ef5f@cherry.de/
[7] https://lore.kernel.org/all/DIFUR95B2LWG.3GMMOVGQ5SIVT@bootlin.com/

Greets,
Dawid

Re: [docs] [PATCH v4] doc: bitbake-user-manual-metadata: document inherit_defer limitations

[Antonin Godard]

On Sat May 16, 2026 at 9:11 PM CEST, Dawid Bijak via lists.yoctoproject.org wrote:
> Add a warning explaining that anonymous Python functions cannot be
> used to influence inherit_defer, since they run after the directive has
> already been resolved.
>
> Also rename VARNAME to VARIABLE for consistency throughout the
> documentation.
>
> Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
> Signed-off-by: Dawid Bijak <bijak.dawid@gmail.com>
> ---
>  .../bitbake-user-manual-metadata.rst           | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> index 0c7c3ff99..134cf8ff1 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
> @@ -827,17 +827,17 @@ the variable after the line is parsed will take effect. With the :ref:`inherit
>  
>  Here is an example::
>  
> -   inherit_defer ${VARNAME}
> +   inherit_defer ${VARIABLE}
>  
>  One way to achieve a conditional inherit in this case is to use
>  overrides::
>  
> -   VARNAME = ""
> -   VARNAME:someoverride = "myclass"
> +   VARIABLE = ""
> +   VARIABLE:someoverride = "myclass"
>  
>  :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>`
> -defers the evaluation of ``${VARNAME}`` until the end of
> -parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARNAME}``
> +defers the evaluation of ``${VARIABLE}`` until the end of
> +parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARIABLE}``
>  expands to ``myclass``, which is then inherited.
>  
>  Alternatively, you could use an inline Python expression in the
> @@ -853,6 +853,14 @@ In all cases, if the expression evaluates to an
>  empty string, the statement does not trigger a syntax error because it
>  becomes a no-op.
>  
> +.. warning::
> +
> +    Setting or modifying variables within an :ref:`anonymous Python function
> +    <bitbake-user-manual/bitbake-user-manual-metadata:Anonymous Python Functions>`
> +    will have no impact on the value of that variable in an
> +    :ref:`inherit_defer <ref-bitbake-user-manual-metadata-inherit-defer>` directive
> +    as the function runs after the directive has been resolved.
> +
>  See also :term:`BB_DEFER_BBCLASSES` for automatically promoting classes
>  ``inherit`` calls to ``inherit_defer``.
>  

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks!
Antonin