Re: [docs] [PATCH v2 3/5] doc: bitbake-user-manual-ref-variables: expand and reorganize BBMASK explanations

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

Hi,

On Mon Feb 16, 2026 at 11:36 AM 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. So let's explain that.
>
> This also explains that this doesn't prevent more than the intended path
> to be caught, specifically because it is NOT a regular expression
> matching an absolute path.
>
> Because any pattern not starting with a ^ character can match multiple
> directories from multiple directories, let's make the usage of
> BBFILE_PATTERN_my-layer the recommended one. Keep the rest as hints at
> what can happen when not using but reiterate what users should be using.
>
> Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
>  .../bitbake-user-manual-ref-variables.rst          | 87 +++++++++++++++++++---
>  1 file changed, 78 insertions(+), 9 deletions(-)
>
> 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..06e1112b5 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
> @@ -1052,24 +1052,93 @@ overview of their function and contents.
>  
>        The following example uses a complete regular expression to tell
>        BitBake to ignore all recipe and recipe append files in
> -      ``meta-ti/recipes-misc/`` directories (and their subdirectories)::
> +      ``recipes-bsp`` directory (recursively) of ``meta-ti``::
>  
> -         BBMASK = "/meta-ti/recipes-misc/"
> +         BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
>  
>        If you want to mask out multiple directories or recipes, you can
>        specify multiple regular expression fragments. This next example
>        masks out multiple directories and individual recipes::
>  
> -         BBMASK += "/meta-ti/recipes-ti/packagegroup/"
> -         BBMASK += "/meta-oe/recipes-support/"
> -         BBMASK += "/meta-foo/.*/openldap"
> -         BBMASK += "opencv.*\.bbappend"
> -         BBMASK += "lzma"
> +         BBMASK += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal/"
> +         BBMASK += "${BBFILE_PATTERN_openembedded-layer}/recipes-support/"
> +         BBMASK += "${BBFILE_PATTERN_openembedded-layer}/.*/openldap"
> +         BBMASK += "${BBFILE_PATTERN_meta-ti}/.*/optee.*\.bbappend"
> +
> +      This masks the ``recipes-graphics/libgal/`` from ``meta-ti``, everything
> +      under ``recipes-support`` in ``meta-oe``, every directory or file whose
> +      name starts with ``openldap`` in ``meta-oe`` at any directory depth > 1
> +      (e.g. in ``meta-oe``, ``recipes-foo/openldap-stuff/`` or
> +      ``recipes-bar/baz/openldap_0.1.bb`` but not ``openldap/``), every append
> +      file in ``meta-ti`` at any directory depth > 1 (e.g.

s/every append file/every append file starting with ``optee``/ ?

> +      ``optee/optee-examples_%.bbappend`` and
> +      ``recipes-security/optee/optee-client_%.bbappend``).
>  
>        .. note::
>  
> -         When specifying a directory name, use the trailing slash character
> -         to ensure you match just that directory name.
> +         Because these are complete regular expressions, if you want to match a
> +         directory and not a file, you must end the expression with a trailing
> +         slash. That is::
> +
> +            BBMASK += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal/"
> +
> +         Will match anything under ``recipes-graphics/ligbal/`` directory of
> +         ``meta-ti``. And::
> +
> +            BBMASK += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal"
> +
> +         Will match in ``meta-ti`` any file prefixed with ``libgal`` in
> +         ``recipes-graphics/`` and any directory (recursively; and its
> +         recipes and recipe append files regardless how they are named) prefixed
> +         with ``libgal`` in ``recipes-graphics/``. That is, provided your layers
> +         are available at ``/build/layers/``, it'll match::

s/build/builds/

Looks good otherwise, thanks for the reorganization!

Antonin