[3/4] doc: bitbake-user-manual-ref-variables: clarify BBMASK matching patterns

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

The documentation doesn't explain the side-effect of putting a leading
slash, only the trailing slash.

The leading slash is not for making the regular expression match an
absolute path, but to force the match on the directory or file that
exactly starts (and ends if there is a trailing slash) with the
specified string.

Finally, this also explains that this still doesn't prevent more than
the intended path to be caught up, specifically because it is NOT a
regular expression matching an absolute path. For that though, the user
can use BBFILE_PATTERN set for the layer they want to mask the recipe or
append files to BitBake. This is typically a regex starting with
^${LAYERDIR}, making it an absolute path matching.

Let's document those limitations.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-ref-variables.rst          | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

Hi,

On Wed Feb 11, 2026 at 7:06 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> From: Quentin Schulz <quentin.schulz@cherry.de>
>
> The documentation doesn't explain the side-effect of putting a leading
> slash, only the trailing slash.
>
> The leading slash is not for making the regular expression match an
> absolute path, but to force the match on the directory or file that
> exactly starts (and ends if there is a trailing slash) with the
> specified string.
>
> Finally, this also explains that this still doesn't prevent more than
> the intended path to be caught up, specifically because it is NOT a
> regular expression matching an absolute path. For that though, the user
> can use BBFILE_PATTERN set for the layer they want to mask the recipe or
> append files to BitBake. This is typically a regex starting with
> ^${LAYERDIR}, making it an absolute path matching.
>
> Let's document those limitations.
>
> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
>  .../bitbake-user-manual-ref-variables.rst          | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> index f20a9012c..6612dcc03 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -1071,6 +1071,28 @@ overview of their function and contents.
>           When specifying a directory name, use the trailing slash character
>           to ensure you match just that directory name.
>  
> +      .. note::
> +
> +         The leading slash in a regular expression in :term:`BBMASK` does not
> +         mean the path is absolute. It simply forces the directory to be named
> +         exactly that. Take::
> +
> +            BBMASK = "meta-ti/recipes-bsp/"
> +
> +        If you happen to have a directory ``my-meta-ti/recipes-bsp``, it will
> +        be matched.
> +
> +        Leading with a slash::
> +
> +           BBMASK = "/meta-ti/recipes-bsp/"
> +
> +        makes sure that doesn't happen. However, this doesn't prevent matching a
> +        directory ``meta-foo/meta-ti/recipes-bsp``. For that, use the
> +        appropriate :term:`BBFILE_PATTERN` to only match a directory from one
> +        specific layer::
> +
> +           BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"

So this looks this is actually what most users want to do, right? Wouldn't it be
better to put this forward instead of in a note, say, at the beginning of the
definition?

For example, replacing the first example in the variable's definition by:

-The following example uses a complete regular expression to tell
-BitBake to ignore all recipe and recipe append files in the
-``meta-ti/recipes-misc/`` directory::
-
-   BBMASK = "meta-ti/recipes-misc/"
+The following example uses a complete regular expression to tell BitBake to
+ignore all recipe and recipe append files in the ``recipes-misc/`` directory
+and subdirectories of the ``meta-ti`` layer::
+
+   BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"

What do you think?

Antonin

Hi Antonin,

On 2/12/26 9:58 AM, Antonin Godard wrote:
> Hi,
> 
> On Wed Feb 11, 2026 at 7:06 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
>> From: Quentin Schulz <quentin.schulz@cherry.de>
>>
>> The documentation doesn't explain the side-effect of putting a leading
>> slash, only the trailing slash.
>>
>> The leading slash is not for making the regular expression match an
>> absolute path, but to force the match on the directory or file that
>> exactly starts (and ends if there is a trailing slash) with the
>> specified string.
>>
>> Finally, this also explains that this still doesn't prevent more than
>> the intended path to be caught up, specifically because it is NOT a
>> regular expression matching an absolute path. For that though, the user
>> can use BBFILE_PATTERN set for the layer they want to mask the recipe or
>> append files to BitBake. This is typically a regex starting with
>> ^${LAYERDIR}, making it an absolute path matching.
>>
>> Let's document those limitations.
>>
>> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>> ---
>>   .../bitbake-user-manual-ref-variables.rst          | 22 ++++++++++++++++++++++
>>   1 file changed, 22 insertions(+)
>>
>> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>> index f20a9012c..6612dcc03 100644
>> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
>> @@ -1071,6 +1071,28 @@ overview of their function and contents.
>>            When specifying a directory name, use the trailing slash character
>>            to ensure you match just that directory name.
>>   
>> +      .. note::
>> +
>> +         The leading slash in a regular expression in :term:`BBMASK` does not
>> +         mean the path is absolute. It simply forces the directory to be named
>> +         exactly that. Take::
>> +
>> +            BBMASK = "meta-ti/recipes-bsp/"
>> +
>> +        If you happen to have a directory ``my-meta-ti/recipes-bsp``, it will
>> +        be matched.
>> +
>> +        Leading with a slash::
>> +
>> +           BBMASK = "/meta-ti/recipes-bsp/"
>> +
>> +        makes sure that doesn't happen. However, this doesn't prevent matching a
>> +        directory ``meta-foo/meta-ti/recipes-bsp``. For that, use the
>> +        appropriate :term:`BBFILE_PATTERN` to only match a directory from one
>> +        specific layer::
>> +
>> +           BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
> 
> So this looks this is actually what most users want to do, right? Wouldn't it be
> better to put this forward instead of in a note, say, at the beginning of the
> definition?
> 
> For example, replacing the first example in the variable's definition by:
> 
> -The following example uses a complete regular expression to tell
> -BitBake to ignore all recipe and recipe append files in the
> -``meta-ti/recipes-misc/`` directory::
> -
> -   BBMASK = "meta-ti/recipes-misc/"
> +The following example uses a complete regular expression to tell BitBake to
> +ignore all recipe and recipe append files in the ``recipes-misc/`` directory
> +and subdirectories of the ``meta-ti`` layer::
> +
> +   BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
> 

Yeah I was conflicted... not sure what's best. This does also rely on 
BBFILE_PATTERN_meta-ti starting with ^ otherwise we have another 
potential name clash and we don't actually mention that in the 
documentation of BBFILE_PATTERN (though it is set like that when 
creating a layer with bitbake-layers create-layer).

If for some reason you have:

/layers/meta-ti/recipes-bsp
/downstream/my-layer/appends/layers/meta-ti/recipes-bsp

then both would be matched (I assume, I haven't checked). That is very 
much a corner case.

I'm also pretty sure nobody actually does that. The only layer I have in 
my pool of cloned layers which uses BBMASK is meta-lts-mixins and then 
doesn't even have the layer name in the paths so /me shrugs.

> What do you think?
> 

We could start with the BBFILE_PATTERN thingy, then explain there are 
other less restrictive ways to match multiple recipes or directories 
from different locations later on. Not sure what's best.

Cheers,
Quentin

Hi,

On Thu Feb 12, 2026 at 12:38 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
[...]
>> So this looks this is actually what most users want to do, right? Wouldn't it be
>> better to put this forward instead of in a note, say, at the beginning of the
>> definition?
>> 
>> For example, replacing the first example in the variable's definition by:
>> 
>> -The following example uses a complete regular expression to tell
>> -BitBake to ignore all recipe and recipe append files in the
>> -``meta-ti/recipes-misc/`` directory::
>> -
>> -   BBMASK = "meta-ti/recipes-misc/"
>> +The following example uses a complete regular expression to tell BitBake to
>> +ignore all recipe and recipe append files in the ``recipes-misc/`` directory
>> +and subdirectories of the ``meta-ti`` layer::
>> +
>> +   BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
>> 
>
> Yeah I was conflicted... not sure what's best. This does also rely on 
> BBFILE_PATTERN_meta-ti starting with ^ otherwise we have another 
> potential name clash and we don't actually mention that in the 
> documentation of BBFILE_PATTERN (though it is set like that when 
> creating a layer with bitbake-layers create-layer).
>
> If for some reason you have:
>
> /layers/meta-ti/recipes-bsp
> /downstream/my-layer/appends/layers/meta-ti/recipes-bsp
>
> then both would be matched (I assume, I haven't checked). That is very 
> much a corner case.
>
> I'm also pretty sure nobody actually does that. The only layer I have in 
> my pool of cloned layers which uses BBMASK is meta-lts-mixins and then 
> doesn't even have the layer name in the paths so /me shrugs.
>
>> What do you think?
>> 
>
> We could start with the BBFILE_PATTERN thingy, then explain there are 
> other less restrictive ways to match multiple recipes or directories 
> from different locations later on.

Yes, I think we should do that

Antonin