| Message ID | 20260216-bbmask-slashes-v2-3-b9bb52f5fd3d@cherry.de |
|---|---|
| State | Not Applicable |
| Headers | show |
| Series | doc: bitbake-user-manual-ref-variables: clarify BBMASK examples | expand |
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
Hi Antonin, On 2/17/26 11:18 AM, Antonin Godard wrote: > 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``/ ? > I'm going for: every append file whose name starts with ``optee`` in does that work for you? >> + ``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/ > Mmmm.. Now to come to think of it, should I use /bitbake-builds/poky-master-poky-distro_poky-machine_qemux86-64/layers/ instead? It would match the instructions in doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst (but it'll make for very long lines :/). Cheers, Quentin
Hi, On Tue Feb 17, 2026 at 12:52 PM CET, Quentin Schulz wrote: > Hi Antonin, > > On 2/17/26 11:18 AM, Antonin Godard wrote: >> 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``/ ? >> > > I'm going for: > > every append file whose name starts with ``optee`` in > > does that work for you? Works for me! >>> + ``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/ >> > > Mmmm.. Now to come to think of it, should I use > > /bitbake-builds/poky-master-poky-distro_poky-machine_qemux86-64/layers/ I think the default name should be "poky-master" now (doc needs an update). > instead? It would match the instructions in > doc/bitbake-user-manual/bitbake-user-manual-environment-setup.rst (but > it'll make for very long lines :/). So /bitbake-builds/poky-master/layers/ is reasonable I think Antonin
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. + ``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:: + + /builds/layers/meta-ti/recipes-graphics/libgal.bb + /builds/layers/meta-ti/recipes-graphics/libgal_%.bbappend + /builds/layers/meta-ti/recipes-graphics/libgal-foo/foo.bb + /builds/layers/meta-ti/recipes-graphics/libgal-foo/foo/bz.bbappend + /builds/layers/meta-ti/recipes-graphics/libgal/bar.bb + + .. note:: + + Because these are complete regular expressions, failing to start the + pattern with a ``^`` sign (which is usually the first character in + :term:`BBFILE_PATTERN`) means it can match *any* portion of a path. + Take the following as an example:: + + BBMASK = "recipes-graphics/libgal/" + + This will match subdirectories and files in any path containing + ``recipes-graphics/libgal/``, meaning (considering your layers are + available at ``/builds/layers/``):: + + /builds/layers/meta-ti/recipes-graphics/libgal/ + /builds/layers/my-layer/foo-recipes-graphics/libgal/ + + will be both matched. This may be a more relaxed way of matching + directories, recipes and recipe append files from any third party layer + but is generally discouraged as it may be casting too wide of a net. + + .. note:: + + Because these are complete regular expressions, a leading slash does + not mean the path is absolute. It simply forces the directory to be + named exactly that. Take:: + + BBMASK = "recipes-graphics/libgal/" + + If you happen to have a directory ``foo-recipes-graphics/libgal/``, it + will be matched. + + Leading with a slash:: + + BBMASK = "/recipes-graphics/libgal/" + + makes sure that doesn't happen. However, this doesn't prevent matching + a directory ``recipes-graphics/libgal/`` from another layer. + + Again, we highly recommend using :term:`BBFILE_PATTERN` in the + expressions to specify absolute paths specific to one layer. :term:`BBMULTICONFIG` Enables BitBake to perform multiple configuration builds and lists