[PATCH v3 0/5] doc: bitbake-user-manual-ref-variables: clarify BBMASK examples

[PATCH v3 0/5] doc: bitbake-user-manual-ref-variables: clarify BBMASK examples

[Quentin Schulz]

Robert reported being confused by the leading slash inconsistencies in
our BBMASK examples and wondered if it had any significance. Myself not
being less confused, I went reading the code and testing, and it does
have significance, so this tries to explain the difference and why you
would want a leading slash in most cases.

It also explains that still with only a leading slash there could be
involuntary matches, which one should be able to get rid of by using
BBFILE_PATTERN from the layer they want to mask recipe or append files
from.

While at it, update the meta-ti example such that it matches what's
currently in the repo (migrated in kirkstone from a single meta-ti git
repo layer to a meta-ti git repo with multiple layers, such as
meta-ti-bsp).

This reorganizes examples such that the ones with BBFILE_PATTERN are the
ones we provide as first examples as those are the ones users should
typically be using such that the masks only apply to a specific layer.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
Changes in v3:
- switched to a list to explain the multiple matching rules for the
  example with multiple BBMASK such that it's easier to digest,
- added missing words here and there,
- reworded the openldap explanation to make it clear it matches
  everything under an openldap directory,
- added missing naming scheme for optee file match rule,
- switched absolute paths from /builds/ to /bitbake-builds/poky-master/
  such that it matches the layout when using bitbake-setup,
- Link to v2: https://patch.msgid.link/20260216-bbmask-slashes-v2-0-b9bb52f5fd3d@cherry.de

Changes in v2:
- added patch 5,
- completely reorganize patch 3 such that the examples with
  BBFILE_PATTERN are the ones provided by default,
- Link to v1: https://patch.msgid.link/20260211-bbmask-slashes-v1-0-b72161c647ef@cherry.de

---
Quentin Schulz (5):
      doc: bitbake-user-manual-ref-variables: clarify BBMASK directory matching
      doc: bitbake-user-manual-ref-variables: have directory examples be consistent
      doc: bitbake-user-manual-ref-variables: expand and reorganize BBMASK explanations
      doc: bitbake-user-manual-ref-variables: update BBMASK example with current meta-ti
      doc: bitbake-user-manual-ref-variables: update Python re doc link to HTTPS

 .../bitbake-user-manual-ref-variables.rst          | 95 +++++++++++++++++++---
 1 file changed, 84 insertions(+), 11 deletions(-)
---
base-commit: 8b635a400152bb40beaa0d7a47181febb43f5c84
change-id: 20260211-bbmask-slashes-7ea904bf6347

Best regards,
--  
Quentin Schulz <quentin.schulz@cherry.de>

[PATCH v3 1/5] doc: bitbake-user-manual-ref-variables: clarify BBMASK directory matching

[Quentin Schulz]

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

BBMASK matches files in the directories matching the regex, and also in
their respective subdirectories, so make that clear in the wording
leading to the example.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 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 4b3b10d46..18bbd638d 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1051,8 +1051,8 @@ overview of their function and contents.
       documentation at http://docs.python.org/3/library/re.html.
 
       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::
+      BitBake to ignore all recipe and recipe append files in
+      ``meta-ti/recipes-misc/`` directories (and their subdirectories)::
 
          BBMASK = "meta-ti/recipes-misc/"
 

-- 
2.53.0

[PATCH v3 2/5] doc: bitbake-user-manual-ref-variables: have directory examples be consistent

[Quentin Schulz]

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

It's a bit confusing to have a mix of paths with and without a leading
slash. The behavior is actually different. The next commit will explain
when/why to add a leading slash.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 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 18bbd638d..f20a9012c 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1054,13 +1054,13 @@ overview of their function and contents.
       BitBake to ignore all recipe and recipe append files in
       ``meta-ti/recipes-misc/`` directories (and their subdirectories)::
 
-         BBMASK = "meta-ti/recipes-misc/"
+         BBMASK = "/meta-ti/recipes-misc/"
 
       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-misc/ meta-ti/recipes-ti/packagegroup/"
+         BBMASK += "/meta-ti/recipes-ti/packagegroup/"
          BBMASK += "/meta-oe/recipes-support/"
          BBMASK += "/meta-foo/.*/openldap"
          BBMASK += "opencv.*\.bbappend"

-- 
2.53.0

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

[Quentin Schulz]

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 layers, 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 the variable but reiterate that users
should be really be using that variable.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-ref-variables.rst          | 91 +++++++++++++++++++---
 1 file changed, 82 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..2564a21a0 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,97 @@ 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:
+
+      - everything under the ``recipes-graphics/libgal/`` directory from
+        ``meta-ti``,
+      - everything under the ``recipes-support/`` directory in ``meta-oe``,
+      - everything under a directory whose name starts with ``openldap``, and
+        every file with the same naming scheme, 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 whose name starts with ``optee`` 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 ``/bitbake-builds/poky-master/layers/``, it'll match::
+
+            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal.bb
+            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal_%.bbappend
+            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal-foo/foo.bb
+            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal-foo/foo/bz.bbappend
+            /bitbake-builds/poky-master/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 ``/bitbake-builds/poky-master/layers/``)::
+
+            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal/
+            /bitbake-builds/poky-master/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

-- 
2.53.0

[PATCH v3 4/5] doc: bitbake-user-manual-ref-variables: update BBMASK example with current meta-ti

[Quentin Schulz]

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

meta-ti git repo now has multiple layers in it since kirkstone, so let's
update the examples to match the current state of meta-ti by using
meta-ti-bsp.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 .../bitbake-user-manual-ref-variables.rst          | 34 +++++++++++-----------
 1 file changed, 17 insertions(+), 17 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 2564a21a0..bab5252e9 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1052,30 +1052,30 @@ 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
-      ``recipes-bsp`` directory (recursively) of ``meta-ti``::
+      ``recipes-bsp`` directory (recursively) of ``meta-ti-bsp``::
 
-         BBMASK = "${BBFILE_PATTERN_meta-ti}/recipes-bsp/"
+         BBMASK = "${BBFILE_PATTERN_meta-ti-bsp}/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 += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal/"
+         BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal/"
          BBMASK += "${BBFILE_PATTERN_openembedded-layer}/recipes-support/"
          BBMASK += "${BBFILE_PATTERN_openembedded-layer}/.*/openldap"
-         BBMASK += "${BBFILE_PATTERN_meta-ti}/.*/optee.*\.bbappend"
+         BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/.*/optee.*\.bbappend"
 
       This masks:
 
       - everything under the ``recipes-graphics/libgal/`` directory from
-        ``meta-ti``,
+        ``meta-ti-bsp``,
       - everything under the ``recipes-support/`` directory in ``meta-oe``,
       - everything under a directory whose name starts with ``openldap``, and
         every file with the same naming scheme, 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 whose name starts with ``optee`` in ``meta-ti`` at any
-        directory depth > 1 (e.g. ``optee/optee-examples_%.bbappend`` and
+      - every append file whose name starts with ``optee`` in ``meta-ti-bsp`` at
+        any directory depth > 1 (e.g. ``optee/optee-examples_%.bbappend`` and
         ``recipes-security/optee/optee-client_%.bbappend``).
 
       .. note::
@@ -1084,24 +1084,24 @@ overview of their function and contents.
          directory and not a file, you must end the expression with a trailing
          slash. That is::
 
-            BBMASK += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal/"
+            BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal/"
 
          Will match anything under ``recipes-graphics/ligbal/`` directory of
-         ``meta-ti``. And::
+         ``meta-ti-bsp``. And::
 
-            BBMASK += "${BBFILE_PATTERN_meta-ti}/recipes-graphics/libgal"
+            BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal"
 
-         Will match in ``meta-ti`` any file prefixed with ``libgal`` in
+         Will match in ``meta-ti-bsp`` 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 ``/bitbake-builds/poky-master/layers/``, it'll match::
 
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal.bb
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal_%.bbappend
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal-foo/foo.bb
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal-foo/foo/bz.bbappend
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal/bar.bb
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal.bb
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal_%.bbappend
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal-foo/foo.bb
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal-foo/foo/bz.bbappend
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal/bar.bb
 
       .. note::
 
@@ -1116,7 +1116,7 @@ overview of their function and contents.
          ``recipes-graphics/libgal/``, meaning (considering your layers are
          available at ``/bitbake-builds/poky-master/layers/``)::
 
-            /bitbake-builds/poky-master/layers/meta-ti/recipes-graphics/libgal/
+            /bitbake-builds/poky-master/layers/meta-ti/meta-ti-bsp/recipes-graphics/libgal/
             /bitbake-builds/poky-master/layers/my-layer/foo-recipes-graphics/libgal/
 
          will be both matched. This may be a more relaxed way of matching

-- 
2.53.0

[PATCH v3 5/5] doc: bitbake-user-manual-ref-variables: update Python re doc link to HTTPS

[Quentin Schulz]

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

It's 2026, use HTTPS for the link.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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 bab5252e9..d867f74ec 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
+++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst
@@ -1048,7 +1048,7 @@ overview of their function and contents.
       compiler. Consequently, the syntax follows Python's Regular
       Expression (re) syntax. The expressions are compared against the full
       paths to the files. For complete syntax information, see Python's
-      documentation at http://docs.python.org/3/library/re.html.
+      documentation at https://docs.python.org/3/library/re.html.
 
       The following example uses a complete regular expression to tell
       BitBake to ignore all recipe and recipe append files in

-- 
2.53.0

Re: [docs] [PATCH v3 0/5] doc: bitbake-user-manual-ref-variables: clarify BBMASK examples

[Antonin Godard]

For the series:

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks!
Antonin