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

["Antonin Godard" <antonin.godard@bootlin.com>]

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