[v2] doc: bitbake-user-manual-intro: improve bbappend file matching doc

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

The recipe name matching wasn't fully explained and were missing a few
important corner cases such as recipes without a version, or using the %
character outside of the version part of the filename for example.

This adds the last missing bits to cover every append naming scenario
that exist today.

This was derived from lib/bb/cooker.py:get_file_appends().

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Changes in v2:
- fixed typo for bbappend named bb,
- added "a" before "``mesa.bb`` recipe",
- Link to v1: https://patch.msgid.link/20260128-bbappend-matching-v1-1-29fef2d63489@cherry.de
---
 .../bitbake-user-manual-intro.rst                  | 51 +++++++++++++++++-----
 1 file changed, 40 insertions(+), 11 deletions(-)


---
base-commit: cdd79c1768ac396a9c6577e38098da4331507f24
change-id: 20260128-bbappend-matching-d0b5252a1179

Best regards,

Hi,

On Thu Jan 29, 2026 at 11:07 AM CET, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@cherry.de>
>
> The recipe name matching wasn't fully explained and were missing a few
> important corner cases such as recipes without a version, or using the %
> character outside of the version part of the filename for example.
>
> This adds the last missing bits to cover every append naming scenario
> that exist today.

Thanks, this was indeed missing!

> This was derived from lib/bb/cooker.py:get_file_appends().
>
> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
> Changes in v2:
> - fixed typo for bbappend named bb,
> - added "a" before "``mesa.bb`` recipe",
> - Link to v1: https://patch.msgid.link/20260128-bbappend-matching-v1-1-29fef2d63489@cherry.de
> ---
>  .../bitbake-user-manual-intro.rst                  | 51 +++++++++++++++++-----
>  1 file changed, 40 insertions(+), 11 deletions(-)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> index baad71304..69ad6037b 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> @@ -271,12 +271,9 @@ same root filename. The filenames can differ only in the file type
>  suffix used (e.g. ``formfactor_0.0.bb`` and
>  ``formfactor_0.0.bbappend``).
>  
> -Information in append files extends or overrides the information in the
> -underlying, similarly-named recipe files.
> -
>  When you name an append file, you can use the "``%``" wildcard character
> -to allow for matching recipe names. For example, suppose you have an
> -append file named as follows::
> +to allow for a less strict recipe name matching. For example, suppose you have
> +an append file named as follows::
>  
>    busybox_1.21.%.bbappend
>  
> @@ -290,12 +287,6 @@ the append file would match the following recipe names::
>    busybox_1.21.10.bb
>    busybox_1.21.11.bb
>  
> -.. note::
> -
> -   The use of the " % " character is limited in that it only works directly in
> -   front of the .bbappend portion of the append file's name. You cannot use the
> -   wildcard character in any other location of the name.
> -
>  If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
>  append name would not match. However, if you named the append file
>  ``busybox_1.%.bbappend``, then you would have a match.
> @@ -303,6 +294,44 @@ append name would not match. However, if you named the append file
>  In the most general case, you could name the append file something as
>  simple as ``busybox_%.bbappend`` to be entirely version independent.
>  

I would wrap from here...

> +The "``%``" character is a marker for BitBake, and everything after that marker
> +will not be used for matching recipe names. That is, an append file named::
> +
> +   busybox_1.%.11.bbappend
> +
> +will match recipes named::
> +
> +   busybox_1.0.11.bb
> +   busybox_1.2.bb
> +   busybox_1.3.48.bb
> +
> +Note that the "``%``" character is not specific to the version part of the
> +recipe name. That is, an append file named::
> +
> +   linux-yocto%.bbappend
> +
> +will match recipes named::
> +
> +   linux-yocto.bb
> +   linux-yocto_6.18.bb
> +   linux-yocto-tiny_6.12.bb
> +   linux-yocto-rt_6.16.bb
> +
> +While it can be useful to append to similar recipes with slightly different
> +names, it is highly discouraged to do so as recipes from other layers may be
> +named similarly enough that the append file would unwittingly match them.

...to there under a .. note:: block. First because it will make it separate from
the first part of this section, and second because it will highlight that this
is an in-depth explanation of this percent sign, not really a standard use.

I would however move what's below from here...

> +A recipe named without a version may only be appended by an append file named
> +exactly the same. That is, a recipe named::
> +
> +   mesa.bb
> +
> +can only be appended by an append file named::
> +
> +   mesa.bbappend
> +
> +That is, ``mesa_%.bbappend`` append file will not match a ``mesa.bb`` recipe.
> +

...to there _above_ the ..note block as this is a pretty standard bbappend
use-case.

Thanks,
Antonin

Hi Antonin,

On 1/30/26 3:06 PM, Antonin Godard wrote:
> Hi,
> 
> On Thu Jan 29, 2026 at 11:07 AM CET, Quentin Schulz wrote:
>> From: Quentin Schulz <quentin.schulz@cherry.de>
>>
>> The recipe name matching wasn't fully explained and were missing a few
>> important corner cases such as recipes without a version, or using the %
>> character outside of the version part of the filename for example.
>>
>> This adds the last missing bits to cover every append naming scenario
>> that exist today.
> 
> Thanks, this was indeed missing!
> 
>> This was derived from lib/bb/cooker.py:get_file_appends().
>>
>> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>> ---
>> Changes in v2:
>> - fixed typo for bbappend named bb,
>> - added "a" before "``mesa.bb`` recipe",
>> - Link to v1: https://patch.msgid.link/20260128-bbappend-matching-v1-1-29fef2d63489@cherry.de
>> ---
>>   .../bitbake-user-manual-intro.rst                  | 51 +++++++++++++++++-----
>>   1 file changed, 40 insertions(+), 11 deletions(-)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> index baad71304..69ad6037b 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
>> @@ -271,12 +271,9 @@ same root filename. The filenames can differ only in the file type
>>   suffix used (e.g. ``formfactor_0.0.bb`` and
>>   ``formfactor_0.0.bbappend``).
>>   
>> -Information in append files extends or overrides the information in the
>> -underlying, similarly-named recipe files.
>> -
>>   When you name an append file, you can use the "``%``" wildcard character
>> -to allow for matching recipe names. For example, suppose you have an
>> -append file named as follows::
>> +to allow for a less strict recipe name matching. For example, suppose you have
>> +an append file named as follows::
>>   
>>     busybox_1.21.%.bbappend
>>   
>> @@ -290,12 +287,6 @@ the append file would match the following recipe names::
>>     busybox_1.21.10.bb
>>     busybox_1.21.11.bb
>>   
>> -.. note::
>> -
>> -   The use of the " % " character is limited in that it only works directly in
>> -   front of the .bbappend portion of the append file's name. You cannot use the
>> -   wildcard character in any other location of the name.
>> -
>>   If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
>>   append name would not match. However, if you named the append file
>>   ``busybox_1.%.bbappend``, then you would have a match.
>> @@ -303,6 +294,44 @@ append name would not match. However, if you named the append file
>>   In the most general case, you could name the append file something as
>>   simple as ``busybox_%.bbappend`` to be entirely version independent.
>>   
> 
> I would wrap from here...
> 
>> +The "``%``" character is a marker for BitBake, and everything after that marker
>> +will not be used for matching recipe names. That is, an append file named::
>> +
>> +   busybox_1.%.11.bbappend
>> +
>> +will match recipes named::
>> +
>> +   busybox_1.0.11.bb
>> +   busybox_1.2.bb
>> +   busybox_1.3.48.bb
>> +
>> +Note that the "``%``" character is not specific to the version part of the
>> +recipe name. That is, an append file named::
>> +
>> +   linux-yocto%.bbappend
>> +
>> +will match recipes named::
>> +
>> +   linux-yocto.bb
>> +   linux-yocto_6.18.bb
>> +   linux-yocto-tiny_6.12.bb
>> +   linux-yocto-rt_6.16.bb
>> +
>> +While it can be useful to append to similar recipes with slightly different
>> +names, it is highly discouraged to do so as recipes from other layers may be
>> +named similarly enough that the append file would unwittingly match them.
> 
> ...to there under a .. note:: block. First because it will make it separate from
> the first part of this section, and second because it will highlight that this
> is an in-depth explanation of this percent sign, not really a standard use.
> 

Do you want two separate notes for busybox_1.%.11 and linux-yocto% 
examples? They both are related to % being a marker so I guess they can 
be added in the same note, but while the former example is definitely 
wrong, the latter may sometimes be found (but is mostly wrong as well, 
but in more insidious ways).

Cheers,
Quentin

On Fri Jan 30, 2026 at 3:54 PM CET, Quentin Schulz wrote:
[...]
> Do you want two separate notes for busybox_1.%.11 and linux-yocto% 
> examples? They both are related to % being a marker so I guess they can 
> be added in the same note, but while the former example is definitely 
> wrong, the latter may sometimes be found (but is mostly wrong as well, 
> but in more insidious ways).

I think a unique note for both is fine

Antonin